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Introduction 


The following chapters provide general tips on VRML design for worlds and ava¬ 
tars to be used with the blaxxun Platform. It discusses effective VRML design, 
handling of shared objects and shared events, and interfacing between HTML 
and VRML. There are also several extensions on VRML available, which are dis¬ 
cussed in detail. The Scripting and API chapters provide a good resource for 
adding interaction to VRML worlds. Also Advanced techniques like “Dynamic 
3D” are introduced and several useful modules, which are distributed with the 
blaxxun Platform are described in detail. Lots of examples show the use of single 
features and explain the handling. 

Using blaxxun technology it is possible to provide high level relatime 3d using the 
blaxxun Contact VRML Browser plugin or even interactive Multi-User-3d without 
the need of an installed plugin using blaxxun3d, respectively blaxxun Contact 
LE. This guide provides information for authoring on both technologies and 
explains, whenever necessary, the specialites. 





Introduction - 
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Conceptual Overview 


blaxxun’s focus is it’s communication platform. 

We consider 3D environments primarily as a mean to enhance communi¬ 
cation among people. They can be used either as virtual places where people 
can meet and interact, or as simulations of real objects (such as architecture, 
CAD-constructions, airplanes, laptops, ...), where people can show, teach or 
learn these objects in the most effective manner. The latter can be done either 
by meeting within the object (e.g., a house or an airplane) or by showing the 
object to each other (e.g., laptop, mobile). But of course our products also allow 
to produce pure single user 3D visualizations. This is the reason large parts of 
this manual treat the different possibilities to integrate 3D environments within 
our community platform. 

blaxxun products allow you to offer your services java based as well as 
plug-in based. With the java based solution you can reach users on any plat¬ 
form (PC, Mac, Linux,..). They don’t need to commit to download prior to see 
your offerings. The plug-in based solution allows you to extend and enrich your 
offer for those who are willing to the commitment (ideally after they got curious 
with java based solution). This is the reason this manual treats two products at 
the same time: 

The plug-in based Contact following the VRML standard and the java based 
blaxxun3D following the X3D standard, a subset of VRML. 


Integrating 3D with the communication platform 

Making a 3D world a virtual meeting place is as simple as uploading the corre¬ 
sponding VRML or X3D file to the corresponding place folder of the community 
platform. Check the places menu of the content administration interface and 
either update an existing place or create a new one. This already allows you to 
see all other people accessing this place as avatars on their actual position and 
orientation in the 3D world. You can see them moving and looking at the objects 
in the world. However designing 3D environments as a meeting place requires 
some conceptual care. For example doors should be wide enough to allow two 
avatars to pass by each other. Viewpoints should be randomized to avoid that 
people get stuck in each other (see “Random Viewpoint” on page 187 for 
details). Please check our “Design Rules” on page 13 for additional hints. 

To share additional aspects of the 3D environment among it's visitors you can 
use the concept of “blaxxun SharedEvents” on page 125. They allow you to 
make dynamic changes in the 3D environment - such as opening doors, switch¬ 
ing lights, opening the CD bay of a laptop - consistent for all participants. You 
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may determine the degree of persistence of these events: Once switched on, the 
light might burn forever or only until the last person left the place. Short actions 
without status change may need no persistence at all as For the time of their per¬ 
sistence shared events will automatically care for people entering the place later. 
They will see the light on, even when the switch was done before they entered 
the place. 

“blaxxun SharedObject” on page 133 allow participants to dynamically put and 
move 3D Objects in 3D places. Furthermore they provide all the administration 
needed to upload and check these objects as well as to trade with them and to 
carry them from place to place. Examples are furniture placed in homes, ani¬ 
mated pets, video screens or advertising boards. Being stored in the database, 
shared objects are also a simple mean of database integration. For example you 
could use a shared object for a door in the virtual environment. It's status (open/ 
close/locked) could be stored in a custom attribute in the database and though 
be available from other places or applications, such as a control panel showing 
the status of all doors in the community. 

Besides SharedObjects you can use dynamic VRML/X3D to interface between 
3D environment and database (described in the chapter “Dynamic 3D using 
the blaxxun Platform” on page 149). In this case you use the cgi-script & tem¬ 
plates of the platform either to generate the complete 3D-file or parts of it. 

As mentioned in the first paragraph blaxxun's community platform takes care for 
the basic mechanics of integrating a 3D file into the HTML frameset. However 
you might want to know that it uses only the javascript EAI (see chapter “API” on 
page 153) and the embed statements described in “Integrating 3D in HTML” on 
page 111. The chapter Places and Chat of the reference manual gives a detailed 
background. To support smooth transfer between places you should include the 
“SceneChange-Proto” on page 191 in your VRML file. 


Java based blaxxun3D vs. plug-in based Contact3D 

We learned from the market that there are contradicting requirements for virtual 
environments. On the one hand people want a highly realistic and sophisticated 
experience, on the other hand they are not willing to wait for downloads or to 
install software prior to a first experience. 

Fortunately blaxxun finally found a solution by offering different access levels to 
the same virtual environment. 

blaxxun3D (also part of ContactLE) is a only 56K large java applet, which allows 
to access 3D environments without installation and with minimal download. How- 
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ever the 3D environment itself should be equally small and simple. It supports 
the X3D standard developed as a subset of VRML. It can be programmed 
through its java script or java interface. 

blaxxun Contact is a 2MB plug-in which needs explicit installation. It fully sup¬ 
ports hardware acceleration and the latest features of directX and though allows 
to build highly sophisticated virtual environments in a very effective way. It sup¬ 
ports the VRML standard and can be programmed directly in the VRML file using 
VRML script. Additionally it provides APIs for javascript, java and COM. 

This allows the following approaches 

1. Use blaxxun3D only. 

If you can keep the virtual places simple or if you only need to visualize 
one product at a time, you only need to provide content for blaxxun3D 

2. Use blaxxun3D as a showcase. 

If you need a sophisticated environment and therefore blaxxun contact, 
you can still provide a simplified showcase using blaxxun3D. blaxxun3D 
users can even meet blaxxun contact users in this environment. 

3. 3. Provide the same environment for blaxxun3D and blaxxun contact. 

Imagine you want to build a virtual exhibition. You could allow each booth 
to be accessed in blaxxun3d as well as in blaxxun contact, but it may 
make sense to provide the halls allowing navigation between the booths 
only for blaxxun contact users. 

Developing content for both blaxxun contact and blaxxun3D 

If you restrict to the supported subset of VRML you can use the same source for 
both viewers. You can even add features not supported by the subset. They will 
be simply ignored by blaxxun3D (but needless increase the download size). 
Based on the same core you can create variants with richer textures, animations 
or details for blaxxun contact. 

Programming interactivity (i.e., a color change triggered by clicking an object) is 
bit more sophisticated. The normal way to do it in VRML is a VRML script. How¬ 
ever VRML script is not supported by X3D, where you normally would do it via 
the java API. Unfortunately the Java APIs in VRML and X3D are slightly different. 
The same is true for javascript. 

The good news is that blaxxun with Platform6 supports X3D javascript API calls 
in blaxxun contact additionally to the VRML javascript API calls. This allows for 
single source programming for both viewers. 


blaxxun 


Although shared events are not yet supported in blaxxun3D on a product base 
we can provide you with a proof-of-concept solution for your project. 
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Shared objects are not supported in blaxxun3D. The reason is to keep the simple 
access as simple as possible. However we probably would extend blaxxun3D at 
least to show shared objects when there are projects demanding for it. 





Design Rules 


The success of VRML applications depends on a combination of performance 
and quality. Despite constant increases in computing capacity, 3D realtime 
graphics is still “low-poly” 3D. The display quality of VRML objects or worlds on 
a given PC depends on its CPU speed and graphics card. 

The biggest bottleneck for real-time applications is the Internet connection. The 
goal is to keep load times at a minimum for the user while offering a balanced 
between speed and scene quality. To optimize performance, designers can: 

• Create models with as few polygons as possible. 

• Use textures to simulate details in geometry. 

• Replace lighting with appropriately designed textures. 

• Use special VRML auxiliary objects instead of conventional geometry. 

• Optimize the VRML file with the aid of functions provided by VRML. 

• Compress the VRML file (gzip). 


Dimensions 

The unit of distance in VRML is the meter. Avatars created with blaxxun Avatar 
Studio are on average 1.75 meters tall. Be relatively generous with space when 
creating your worlds, especially for doors and other narrow passages. This will 
ensure that they don’t become obstacles for your users, especially those with 
less experience in navigating VRML worlds. 


Naming conventions 

Always use lowercase letters when naming your files, including folders and tex¬ 
tures. Some operating systems, such as UNIX and Linux, are case-sensitive. 


The VRML Scene Graph 

VRML is an international standard for interactive 3D graphics on the Internet. For 
details about the standard, see the Web3D Consortium’s specifications page 
at http://www.vrml.org/fs_specifications.htm. You can also download the 
VRML97 specification there. 
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In the following example, we’ll briefly describe the scene graph using a block 
generated with 3D Studio MAX. 



Tools 

VrmIPad (http://www.parallelgraphics.com/products/vrmlpad) is a good choice 
since it can interpret VRML syntax with a color-coded display and can also rec¬ 
ognize errors. 


The VRML Scene Graph includes: 

• Nodes, the basic building blocks 

• These nodes are arranged hierarchically and can also contain other 
nodes. 

• There are group, children and object nodes. 

• Each node describes a certain functionality, which is specified in detail by 
fields in the node. 


jvkhi vs o utfs 

f Produced by 3D Studio MAX esrporter. Version 3 01 Revision Q 

9 Date Tue Sep 05 11 59 *9 2D0Q 

DEF QuaderQl Transfora { 

translation -0.05937 0 -0 6933 
ch i 1dren [ 

Transform { 

translation 0 0.3 0 
children [ 

Shape { 

appearance Appearance { 
material Material { 

ditfuseCoIor 0 109B 0.5343 0.5941 

} 

* 

geometry Bdk { size 3 1 2 } 

} 

I > 


Fig. 1: VRML scene graph 

The various components of VRML code are described in the following table. 

#vrml V2 . o ut f 8 This line must appear at the beginning of every VRML 
file to identify it as such. 

def Quaderoi The keyword def (define) is used to assign a name to 
a node; this node can be used later with the use key¬ 
word, optimizing file size and memory use. 
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Transform 


Nodes 

translation 

rotation 

scale 

Shape 

Material 

diffuseColor 
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This is a transform node that takes the block and moves 
it to a certain position in the 3D space and/or performs 
other transformations on it. This node extends from the 
first curly brace {to the last}. 

Nodes have typical characteristics that are more exactly 
specified by fields; for a transform node, these include 
translation, rotation, scale and scaleOrientation. 
Specifies the displacement in x y z. In the VRML coor¬ 
dinate system, x and z form a horizontal plane and y 
points up. 

Defines a rotation with 4 numeric values: a rotation axis 
(x y z) and an angle (w) given in radians. For example, 
a rotation of 180 degress around the y-axis: 0 1 0 3.14 
Defines scale factor for the x, y and z axes. For exam¬ 
ple, scale 2 2 2 scales the object by a factor of 2 in 
the x, y and z directions. 

This is the node that precisely describes the object; it 
has the fields appearance and geometry. 

This node provides details about the object’s appear¬ 
ance. 

Specifies the color values. VRML uses the RGB (addi¬ 
tive) color model. For example, 111= white, 0 0 0 = 
black, 0 0 1= blue. All color values lie between 0 and 1. 


Additional material attributes include: 


ambientlntensity 

shininess 

specularColor 

transparency 

emissiveColor 

Box 


IndexedFaceSet 


Brightness (0 -1); the higher the value, the brighter 
the color. 

specifies the smoothness/polish (0-1) 
the spectral color, i.e. the color value of the shini¬ 
ness (0 0 0) 

specifies the transparency: 0 = opaque, 1 = clear 
specifies the emission color 
In the example above, the geometry is specified by 
the primitive node Box. Other primitives include 
Sphere, Cone and Cylinder. 

This node (a set of polygons) is used to describe 
objects that can’t be described by primitives. 


blaxxun 
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Design Rules - Geometry 


Geometry 

Pay special attention to the number of polygons you use. It is more difficult to cre¬ 
ate an attractive scene with few polygons than with many. When necessary, it is 
easier to add complexity and detail to a scene later than it is to remove it. 

If possible, create your objects or scenes at the origin of coordinates. This makes 
it easier to combine VRML worlds and objects. 

Curves can also be created with few polygons. By using the VRML field 
creaseAngle 3.14 in the geometry node, you can give even low-poly objects 
a soft edge. 

Delete polygons that are never seen by the user, such as bottom sides of 
objects, in order to reduce the amount of polygons that need to be rendered. But 
be careful doing this in order to avoid gaps. 

Avoid doubled polygons. 

Instead of complex geometry, you can use textures or billboards. 

The solid field of the geometry node specifies whether an object is one- or two- 
sided. The statement solid true means that your object is closed and will be 
displayed one-sided. An object such as a flat disk would in this case be invisible 
from underneath. To make it visible from both sides, use solid false to force 
the real-time renderer to calculate the polygon twice; this results in a perfor¬ 
mance hit. 


Z-buffering 

Avoid using closely spaced, parallel surfaces and long, tapered triangles. 

Object penetrations tend to flicker; “sew” objects into scenes. The geometries 
should fit together seamlessly, point-on-point. 


Textures 


VRML supports these texture formats: 

• JPG (Joint Photographic Experts Group) 

• PNG (Portable Network Graphics) 

• GIF (Graphics Interchange Format) 
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axxun 


An alpha channel is required for textures with transparent regions; PNG and GIF 
provide that functionality. 

Keep textures small (image size and number of colors, if possible) to reduce 
download time for the user. Image resolution should be 72 dpi (screen quality, 
like for websites). 

To make efficient use of the texture memory in graphics cards, textures should 
be sized in powers of two, i.e. 32x32, 64x64, 64x128 etc. If possible, they should 
also be square. The maximum texture size that most graphics can deal with is 
512x512 pixels. 

Reduce the number of textures by tiling them or reusing them for several objects. 
Ideally, use a single large texture containing the images for several objects. This 
is more efficient than the use of several small texture files since only one HTTP 
access is needed to download. 



Fig. 2: Texture for a laptop 

For a texture used to display a laptop, different perspectives were assembled 
into one file. 

The Appearance node has a material and a texture node. From a performance 
perspective, this is not good since the material and the texture have to be ren¬ 
dered in real time. You can remove the Material node later during optimization. 

Note: The Material node is necessary to display a transparent object that has no 
alpha channel in its texture. In certain special design conditions, it can prove use¬ 
ful to retain the Material node. 





























Design Rules - Audio files 


Audio files 

Audio files improve the immersive experience a lot. In order to keep the file size 
of audio files as small as possible, you should consider the following rules: 

• wav-files can be gzipped, 

blaxxun Contact notices the compression and automatically unzips the 
files after downloading 

• consider the appropriate quality, 

often the achieved quality of 8 bit, mono with 11 kHz sampling rate is suf¬ 
ficient. 

• Note that blaxxun3D can only play au-files (8 bit, 11 kHz, mono) Read the 
chapter “Audio in blaxxun3D” on page 28 for details. 


Viewpoints 

Viewpoints help the viewer in navigating a VRML scene. With the aid of view¬ 
points, designers can directly influence the positions that users occupy in a 
scene. 

Most 3D tools work with cameras, which are converted to viewpoints during 
VRML export. Viewpoints can also be animated to provide automatic movement 
such as, for example, a tour. 

Viewpoints should be positioned at a height of 1.75m above the ground level of 
a scene; this is the normal viewing height for avatars in blaxxun communities. 

Use the description field to specify a name for a viewpoint; this name will be dis¬ 
played in the blaxxun Contact context menu (displayed by right-clicking in the 
scene). 


Lights 


Use of lights increases the rendering time. Consider carefully whether lighting is 
necessary. The default light in blaxxun Contact is sufficient to show object prop¬ 
erties such as shininess, specular color, etc. Objects with textures are not 
affected by lights, unless they have additional material properties. 






Animation 


Design Rules 



Plan your animations carefully. Use a small number of frames and change the 
cyclelnterval (animation duration) in the VRML code later. If several objects per¬ 
form the same animation, combine them into a group so that the interpolators are 
only included in the file once. 


VRML Optimization 

Some steps in a VRML optimization can already be performed while creating the 
model: 

• Create a model that uses few polygons. 

• Simulate details of geometry with textures. 

• Substitute photorealistic textures for lighting. 

General optimization and performance tips 

• reduce and simplify geometry 

• remove unneeded faces 

• use instancing (DEF once USE many times) 

• don't disable backface culling (solid FALSE) if it is not totally necessary 

• use unlit textures : 

Shape { 

appearance Appearance { 

texture ImageTexture { url "myimage.jpg"} 

} 

geometry ... 

} 

• Share identical Texture, Material and Appearance nodes. 

• Try to combine several textures in one image, and adapt texture coordi¬ 
nates 

• Prescale textures to a power of 2 

• limit the number of lights, Directional Lights are fastest 

• help the browser by limiting the amount of active nodes: 

- using a switch node currently unneeded / invisible parts can be enabled 
/ disabled 


blaxxun 
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Design Rules - VRML Optimization 



- complex animations can be disabled by disabling TimeSensor’s ( e.g. 
enabled FALSE ) 


Optimization for blaxxun Contact (may also be true for other brows¬ 
ers) 

• Specify visibilityLimit in Navigationlnfo for better z-range adaption and for 
more culled geometry 

• Many Text Nodes are expensive, an alternative are textures representing 
text 

• Few IndexedFaceSet's with many faces are more performant than many 
single face IndexedFaceSets with few or only a single face 

• If the plugin is embedded into a frame set any animations like animated 
GIF's in the other frame may slowdown the 3D operation 

• Flat shading can be forced with the default value for creaseAngle 0 and 
normalPerVertex FALSE 

• For unlit materials use Material {diffuseColor 0 0 0 emissiveColor 
yourColorHere } The specularColor is already black by default. 

• Shapes with more than 1024 (hardware) / 2020 vertices (software) or col¬ 
or per face requires some extra preprocessing 

Later the VRML file can be optimized with the aid of the supplied VRML nodes. 
You can perform the optimization manually but, for long files, this is a long and 
not very rewarding procedure. Fortunately, there are tools that can help. 
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For automated optimization, you can use Trapezium’s Chisel (http://www.trape- 
zium.com/Chiselpage. htm). 


Data reduction: 0% 

Polygon count: 32 

+ validate 

No errors, 56 warnings 

+ FORMAT 


CLEAN 

L7 Remove default fields 

18 default 

U7 Remove repeated value refs 

23 repeated 

T7 Remove unused values 

a unused 

r Remove repeated index values 

0 repeated 

F" Remove repeated fields 

0 repeated 

Remove bad faces 

0 bad 

p Remove useless nodes 

3 useless 

, f Move ROUTES to end of file 

0 bad 

f Remove unnecessary interpo late rvalues 0 unnecessary 

Generate diffuseCclOr field tor IF8 

0 single colored 1FS 


Fig. 3: Chisel—Clean feature 

When you open a file with Chisel, it provides a variety of information about the 
file. With Data Reduction, it’s easy to see how much you have already optimized. 
Activate the Validate button to get information about errors and warnings. 

Use the Clean option to receive a list of suggested optimizations. It removes 
fields that are set to default values, for example: 

• The statement solid true is a default setting, so it can be deleted with¬ 
out changing an object’s properties. 

• But solid false is not a default setting and will remain in the code. 
Simply click on the Clean button to carry out the optimization. 

The Condense option also provides a set of optimization suggestions: 

• Activate the Create DEF/USE checkbox to reference complex object or 
appearance descriptions that apply to multiple objects. 

• Activate the Remove material node and remove only if texture is available 
checkboxes to remove an object’s material if a texture is found. 


blaxxun 
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Design Rules - blaxxunSD specifics 


- CONDENSE 

& r Adlust numeric resolution 

6 value nodes 

■t> F Adj u st 1 nte rp ol ato r res o lull o n 

0 interpolators 

|7 Create DEFflJSE 

4£Q£F. 0 USE 

f Create PROTOs for Interpolators 

0 Interpolators 

f Create index fields 

0 unlndexed values 

F Re move empty 1 n d exed F a c eSete 

0 empty 

Remove normals 

0 normal 

£■ Remove unused DEFs 

22 unused 

~~ Remove unused PROTO interface fields 

0 unused 

F Shorten PEF names 

22 DEF, Cl USE 

T Single value interpolator keys 

: F Remove material node 

f V t em pye o nty If textu re aval 1 a b 1 e 


Fig. 4: Chisel—Condense feature 

Note: If an object with a texture is to be transparent, the material values must be 
inserted into the Appearance node with VrmIPad afterward. 

Textures often comprise the biggest portion of the data. Try to find a compres¬ 
sion and size that for your textures that provide attractive appearance and fast 
download times. 

Gzip 

Before releasing your file, compress it with Gzip. This will reduce it to a half or 
even a third of its original size. You can get a command line version of gzip from 

here. 

Bob Crispen provides a windows version of this tool, which can be downloaded 

here. 


blaxxun3D specifics 

Besides all above mentioned rules, you have to be aware of some specifics 
when creating VRML worlds for use in blaxxun3D, the non-plugin alternative for 
viewing 3D content. 

Code cleanup 

blaxxun3D only supports a VRML subset described in the “blaxxun X3D-Propos- 
al” on page 195. The content may only use the featured subset. For existing 
VRML content the steps are: 
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• Eliminate unsupported language features like PROTO, EXTERNPROTO 
and Scripts 

• Eliminate unsupported nodes and fields 

• Fix up lighting. (The DirectionalLight node supports the direction and in¬ 
tensity fields, the Material node, the diffuseColor, emissiveColor and 
transparency fields). 

• Verify that the content still works in VRML browsers like blaxxun Contact 
3D. 

• Create a blaxxun3D applet HTML page. 


In order to do these steps we recommend using the blaxxun3D Wizard, that 
automatically does these steps for you and can be downloaded here. 


Textures 

Another step in VRML content optimization is cleaning up textures: 

• All images must be in JPEG or GIF format. 

• blaxxun3d does not support png textures 

• when using textures, set material node preverably to null. 

• alpha transparencies will only be displayed if material node is null 

• Ideally, texture sizes should be 32x32, 64x64, 128x128, 256x256 or 
512x512. 

• Too large textures or textures in unsupported formats can be processed 
with Tools like Adobe Photoshop or PaintShop Pro. 

Performance 

blaxxun3D uses 100% pure Java for the 3D software rendering. So the speed is 
directly proportional to the applet's display area and the number and covered 
area of the polygons in the view. So methods to increase speed are: 

• Making the applet's width & height numbers smaller 

• reduce the number of polygons for complex meshes 

• use less number of textures 

• use the visibilityLimit in the Navigationlnfo node to draw less geometry at 
large worlds. 

Download optimization 

The download can be optimized using the following techniques: 

• Compress the VRML ASCII source file using gzip. 
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This can be done using the bx3DWizard or using either B.Crispen’s Win¬ 
dows version of gzip or the commandline version: 

gzip -9 content.wri 

rename content.wri.gz content.wri 

• Strip unneeded textual information (indentation, unnecessary decimal 
precision, unneeded node names, etc.) from the VRML file, using Chisel 
for example. 

• Downscale textures and/or use JPEG / GIF optimization programs. 

You can also decide to combine the geometry and all used textures to one com¬ 
pressed archive file. This may be useful for faster download, thus there will only 
be one file that will be fetched from the server by one single http-request, 
whereas multiple http-requests may increase the download time. The 
blaxxun3D Wizard can combine these files for you. See the Wizard documen¬ 
tation for details. 


Multi-User Aspects 

Creating 3D worlds for Multi-User environments can be a big difference com¬ 
pared to single user worlds or objects. Make sure that your concept takes care 
of the requirements. The following aspects may help you with your consider¬ 
ations: 


• Think about the right dimensions. MU worlds should be suiteable for 
many users at the same time. Too small dimensions can be very anoying. 

• Think about Multi-user intercations. The blaxxun Platform offers several 
possibilities that help you creating ’state-of-the-art’ interactivity. User in¬ 
teraction is vey important. Avoid ’dead’ worlds. 

• Make sure, that your user interfaces are understandable. 

• Consider an appropriate download size. 
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General 


blaxxun Contact uses several System ressources to play media files. Besides 
the DirectX components it can also access other installed media players. 
Because of that, it is possible to play much more media types than required from 
the VRML Spec. 

In order to have access to these media assets, it is necessary to use a MovieT- 
exture node, even if the desired media is a pure audio file. 

Please note, that wav-files can be gzipped. blaxxun Contact notices the com¬ 
pression and automatically unzips the files after downloading. Besides that, the 
audio file size may be reduced by audio sampling itself. Read “Audio files” on 
page 18 in the Design Rules section for details. 


Windows Media 

If Microsoft Windows MediaPlayer 6.4 or higher is installed, different Audio and 
Video formats are supported in the MovieTexture node. The URL information is 
passed to Media Players API for streaming. 

The URL protocols mms:// are treated as Window Media Media streamed URLs. 
If the URL starts with the URN urn:inet:blaxxun.com:wm: then the URL string 
after the URN gets passed to Windows Media. The string should denote a fully 
qualified URL. Depending on Network connection this can be used for HTTP 
streaming of MP3's. 

If the URL starts with the URN urn:inet:blaxxun.com:wm_cached: then the 
string after the URN is treated as a common HTTP/FTP URL and the URL is 
downloaded first to the local hard disk and then passed to Windows Media. We 
recommend this method if media are played several times or looped in order to 
avoid looped streaming. 

Sound is decoded and played by Windows Media, so no spatialization of the 
sound is supported. The sound is played in addition to other VRML sounds or 
Contact text to speech with the Direct Sound driver. No status messages are dis¬ 
played, usually the media starts playing after a while, once the buffering phase 
is completed. The initial stream opening currently blocks Contact for a short 
while. 
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In Oder to synchronize animations with streamed content, MovieTexture node 
is extended with an eventOut SFTime mediaTime, where mediaTime reports the 
current play position time. (Please see also “MovieTexture2” on page 93) Moni¬ 
tor this event to start animations. 

The following Media types are supported by Media Player 6.4 
Sound formats: 

MIDI, MP3, WAV, WMA, ASF 
Video Formats: 

MPEG, AVI, ASF, WMV 

ASX files are unsupported. But as an ASX files usually references one mms:// 
stream, you can reference it directly in the mms:// stream in the url field of the 
MovieTexture. 

By default the following file extensions are associated internally to Media Player: 

asf, au, avi, ivf, mid, midi, mpl, mp2, mp3, mp4, mpa, mpv2, mpe, mpeg, mpg, 
mpv, rmi, snd, wav, wma, wmv 


Real Media 

If RealPlayer G2/Real Player Plus G2 or higher is installed, RealAudio and 
RealVideo media are supported. The URL information is passed directly to the 
Real G2 subsystem and is played streamed. 

The URL protocols pnm:// and rtsp:// are treated as Real Media URLs. If the URL 
starts with the URN urn:inet:blaxxun.com:rma: the string after the URN is 
passed to Real G2 as URL. This allows media types to be passed to Real G2 
instead of DirectShow. 

If the URL starts with the URN urn:inet:blaxxun.com:rma_cached: then the 
string after the URN is treated as a common HTTP/FTP URL and the URL is 
downloaded first to the local hard disk and then passed to Real G2. We recom¬ 
mend this method if the media are played several times or looped. 

Sound is decoded and played by RealPlayer G2, so no spatialization or mixing 
with VRML sounds is supported. Only ONE Real G2 stream can play. Parallel 
usage of Real Player is currently not working. No Real status message are dis¬ 
played. The media starts playing after a while, once the the buffering phase is 
completed. 
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In order to synchronize animations with streamed content, the MovieTexture 
node is extended with an eventOut SFTime mediaTime, where mediaTime 
reports the G2 current play position time information. (Please see also 
“MovieTexture2” on page 93) Monitor this to start animations, once the content 
starts playing. 


A broad range of Audio and Video formats are supported by Real G2, if the 
codecs are installed. Examples include 


FLASH (.swf), MP3, m3u MP3 play lists etc. 


By default the following file extensions are associated internally to Media Player: 


ra, ram, rmm, rav, rm, rmp, rv, smil, smi, m3u, pis, swf. 


If a clip is started with a mouse click, we recommend to start the clip by assigning 
to the url. The Media layer already opens the stream with a given url, even when 
the clip is not playing. 


Other Media Types 


MIDI files are not supported in the AudioClip but in the MovieTexture node. 
Example: 


Transform) 

translation 0-10 
children[ 

Shape{ 

appearance Appearance { 
texture MovieTexture { 
url "jazz.mid" 
loop TRUE 
} 


} 

geometry Box {size 0.01 

} 


0.01 0 . 01 } 


} 

If you need to play media types unsupported in VRML 97, Real or Windows 
Media you may always embed them in another (possibly hidden) HTML frame. 

If the media player has a script capable API playing still can be controlled from 
3d. Of course you may embed the Real or Windows Media player too, providing 
the advantage of additional controls like title display, start, stop and volume con¬ 
trols. If the player does not allow to use the DirectSound engine cooperatively 
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(like Real) you need to ensure that no sounds are played in the 3d world while 
the media player is running. 

With the Geometrek DeepWave Winamp plugin you can write 3D VRML anima¬ 
tions driven by spectrum data. 


Audio in blaxxun3D 

There are several restrictions you need to be aware when using blaxxun3D in 
combination with audio. Because the audio file is played by the Java Runtime 
Environment, the url field of an AudioClip node can only point to a pure java 
jdkl .1 compatible audio format. Generally this is: 

AU 8-bit mu raw with a 8khz sampling rate. 

Other audio formats are not supported. You may use jaWavedit to encode your 
wav files to au files 

Also all media URLs must point to the server where the applet will be hosted, i.e. 
relative URLs are recommended. 

Notice that there can be only one AudioClip running at a time. 


Video in blaxxun3D 

Because the MovieTexture node is not supported by the core X3D profile, it is 
not possible to have video files in a 3D scene displayed by blaxxun3D. If you 
want to offer video in combination with your 3D scene, we recommend to open 
the media player as a separate instance. This can simply be done by defining the 
media URL in a common Anchor node: 


Anchor{ 

url"http://www.blaxxun.com/video/blaxxun.ram" 
parameter["target=_blank"] 
children[ 

#some geometry 

] 

} 
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Introduction 

This document provides details about blaxxuns implementation of the Script 
node. 


Script Node 

The Script Node implements VrmIScript and a JavaScript subset as defined in 
Annex C of the VRML97 specification and in the “Proposal for a VrmIScript 
Node Authoring” by Chris Marrin, Jim Kent, that can be found at “VRMLScript 
Reference” on page 240 in the “Related Dokuments” section. 

Supported Script node URL strings are strings that begin with the VrmIScript 
identifier tag "vrmlscript: 11 or with the JavaScript identifier tag "javascript: 11 . The 
latter is treated internally as "vrmlscript: 11 . Scripts may reside in files with the 
extension .vs or .js. 

If the "verbose VRML warnings" switch is on, the console window shows diag¬ 
nostic messages like ‘duplicate defined scipt function’, ‘use of unitialized vari¬ 
ables’ to help debugging script code. 

The "object:" tag allows to embed native COM objects, implementing the blaxxun 
VRML Script COM Interface. For details please read the chapter “COM Inter¬ 
face” on page 160 

Java in the Script node is currently not supported. 


blaxxun3D specifics 

The Script node is not part of the core X3D Proposal and therefor not supported 
by blaxxun3D. In order to add more complex interactivity to VRML worlds dis¬ 
played in blaxxun3D, you may want to use the very flexible and powerful API, 
described in the chapter “blaxxun3D” on page 165 in the API section. 
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blaxxun Contact vrmlscript limitations compared to ECMA 
Script (ECMA) 

1. Vrmlscript statements must be properly terminated with a semicolon (like 
in C or Java). The following statements are invalid and result in error mes¬ 
sages: 

{a=l b=2 if (a) { b=c } return 5 } 

These statements are correct: 

{a=1; b=2; if (a){ b=c; } return 5;} 

2. Vrmlmatrix is treated as single-level array with 16 elements. A constructor 
that initializes the matrix directly with new elements is not supported yet. 
(only supported constructor is vm = new VrmlMatrix();) 

3. Date and Array objects are only partly supported. 

4. with, switch statements and other expressions like eval are not 
supported 

5. Adding new properties to field objects like sfcolor.someNewProperty = x 
is unsupported. 

6. lUndeclared variables are local to a function (like in C or Java); global 
variables are only those declared in the script interface as field, exposed- 
Field or eventOut. 

7. The !=, == operators are not properly supported for objects 

8. If scripts inside PROTOs modify nodes via direct access or browser calls 
like addRoute, deleteRoute and createVrmIFromUrl, the directOutput 
TRUE flag must be set. All nodes of the PROTO definition the script mod¬ 
ifies must be listed directly (e.g. not as children of a Group node) in some 
SFNode or MFNode field of the script. Otherwise the node is shared 
among different instances of the PROTO, resulting in unexpected behav¬ 
ior. 


Optimizing scripts 

Scripts are interpreted. If a scripts runs often (e.g. a scripted complex animation 
in a PROTO instanced several times) authors can therefore speed up scripts by 
common programming techniques. 

Subexpression elimination: 

for (var i=0; i<children.length; i++) 

{ 

mycoord.pts[i]=Math.PI*10*i; 
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Optimized: 


var len= children.length; // precompute & store to local value 
of children.length 

var factor =Math.PI*10; // precompute factor 

for (var i=0 ;i<len;i++) 

{ 

mycoord.pts[i] =factor*i; 

} 

In Contact each assigment mycoord.pts[i] will potentially trigger an event flow 
(Route update). Depending on the logic this is faster: 

var len= children.length; 
var factor =Math.PI*10; 
var newPts = new MFVec3f(); 

newPts.length = len; // preallocate space in newPts 

for (var i=0; i<len; i++) { 

newPts[i]=factor*i; 

} 

mycoord.pts [i] =newPts; // only one update 

Saving a field object reference or using an additional SFNode variable speeds 
up complex node field accesses 

myShape.appearance.material.diffuseColor.r = 1.0; 
myShape.appearance.material.diffuseColor.g = 1.0; 

optimized: 

var field = myShape.appearance.material.diffuseColor; 
field.r = 1.0; 
field.g = 1.0; 

A script which does not receive events does not consume CPU time, so use sen¬ 
sors like ProximitySensor, VisibilitySensor to enable complex computations 
once needed 
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Scripting extensions 
General 



VRML content using the features in this section is NOT compatible with other 
VRML browsers, unless the script contains fallback code for other browsers. 

In the Script node interface exposedFields are allowed. An exposedField 
behaves as a field combined with an eventln and eventOut. This feature often 
simplifies PROTO authoring. 

Example: 

PROTO MyTransform [exposedField SFVec3f translation 123] 

{ 

Transform { translation IS translation } 

Script { 

exposedField SFVec3f translation IS translation 
url "j avascript: 
function translation(v) 

{ 

print('Translation changed to '+v); 

} 

"} 

} 


Assignments to eventOut or assignment to node fields ("directOutput") will 
directly trigger any attached routes. eventOut’s of the Script are not delayed trig¬ 
gered at the end of the Script execution as described in the VRML 97 spec. 


Browser object extensions 

additional member functions 

void print (string) - print the string to the console. A typical use is to debug 
scripts. Too many prints can slow down the performance due to the console 
update. 

function x(value) { Browser.print(' value is '+value); } 

In order to print timestamps easily, the following code fragment can be used: 
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Browser.print('Time = '+ (timestamp - 
Browser.getWorldStartTime() ) ); 

For compatibility with other VRML browsers, the built-in functions 

print (string) and trace (string) are supported. 

createVrmlFromString - ‘knows’ PROTO definitions in the top-level VRML 
file, (non-standard !) 


Time 



float 

getCurrentTime() 

gets the computer's current system 
time 

float 

getTime() 

gets the browser's current simula¬ 
tion time 

float 

getWorldStartTime() 

gets the time the world was loaded 


Avatar 

void setMyAvatar(node) 

bool showMyAvatar(flag) 
bool getThirdPersonView() 


sets the avatar for third-person 
mode display 

toggles third-person mode on/off 
returns state of 3rd persion mode 


Sound 

void setSoundEnabled(flag) 
bool getSoundEnabled() 


set false to lock the usage of the 
sound device for this scene 
returns current state of sound 
enabled state 


Navigation 

void 

setNavigationMode(string) 
string getNavigationMode() 

void 

setCollisionDetection 

(flag) 

bool 

getCollisionDetection() 
void setGravity(flag) 


changes navigation mode 

returns the active navigation mode 
(4.0) 

changes collision detection mode 

returns state of collision detection 

changes gravity = terrain following 
mode 
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bool getGravity() 
void setHeadlight(flag) 
bool getHeadLight() 
void 

setViewpointAnimation 
(flag) 
bool 

getViewpointAnimation() 
void 

setAvatarHeight(float) 

float getAvatarHeight() 
float getStepOverSize() 
void 

setCollisionDistance 

(float) 

float 

getCollisionDistance() 
void 

setVisibilityLimit(float) 
float getVisibilityLimit() 
void setWalkSpeed(float) 


returns current state of gravity 
changes headlight mode 
returns current state of headlight 
If flag is TRUE, viewpoint changes 
are animated otherwise immediate. 

returns current state of viewpoint 
animation 

sets the avatar height, used for com¬ 
puting distance of viewpoint to 
ground 

returns current avatar height 
returns current step over size 
changes the collision distance 

returns current collision distance 

changes visibility limit 

returns current visibility limit 
changes walk speed 
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void setViewpointByValue 
(SFVec3f position, 
SFRotation orientation, 
int mode) 


sets current viewpoint position to 
position / orientation 


Allowed Modes: 


bit 0: 1 animated transistion, 0 not 
animated 

bit 1: 1 sets absolute viewpoint 
(unbind any bound viewpoint) 
bit 2: 1 values are a relative move 
distance (left/right, up/down, > in/ 
out, look left/right, look up/down, 
roll,) 

bit 3: 1 check for collision, 0 not 
bit 4:1 check for ground detection, 0 
not 

You can program custom navigation 
with this function: 

For navigation a new relative move 
distance is computed from user 
input and passed to the Browser as 
Browser.setViewpointByValue(dis- 
tance,rotation,(4+8+16)); 

In relative move (bit 2, value = 4) the 
orientation axis is interpreted as 3 
rotation angles about the relative x, 
y, z axes of the camera. 


returns current viewpoint position 


getViewpointByValue 
(SFVec3f position, 
SFRotation orientation, 
int mode) 


Modes: 

0 : return data of local viewpoint 


1 : global viewpoint, value of local 
viewpoint transformed to global 
coordinates if bound viewpoints is 
inside a Transform Node 

2 : third person mode viewpoint 


Userlnterface 

boolean 

isKeyPressed(int keyCode) 


determines by keyCode if the virtual 
key is currently pressed 
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Node mouseSelect 

(SFVec2f startPoint) 

Computes an intersection of a ray 
from the given 2D mouse position 
with the scene graph. Result is null if 
no intersection found or a PseudoN- 
ode RayHitlnfo. 

URL 

string getWorldBaseURL() 

returns the base URL of the top-level 
world 

string getBaseURLO 

returns the base URL for the script 
node 

loadURLrel 
(MFString url, 

MFString parameters) 

Urls inside EXTERNPROTO 
instanced VRML Nodes are relative 
to the including VRML world, get- 
BaseURL returns the baseUrl of the 
VRML file containing the Script 
node. So this call resolves common 
authoring problems, if URL refer¬ 
ences in the PROTO are relative to 
the implementing PROTO, 
same as loadURL except URL is rel¬ 
ative to getBaseURL() 

Rendering 

void setRenderMode(string) 

changes rendering mode. 

Supported values are ‘Flat’, 
‘Gouraud’, ‘Wireframe’, ‘Vertices’. 
The OpenGL renderer additionally 
supports ‘Solid NonLighted Bound- 
ingBoxes’. 

float getZNearO 
float getZFarO 

returns current znear clipping value 
returns current zfar clipping value 

VRML Browser window 

int getWindowSizeX() 

returns the horizontal size in pixels 
of the rendering window 

int getWindowSizeY() 
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float getwindowAspect () returns the aspect ratio (width/ 

height) of the rendering window, 
useful to adjust overlays 


Client System 

int getcap (int what) returns browser capability informa¬ 

tion. 

Example usage: adapt content to cli 
ent platform, check if a certain fea¬ 
ture like alpha blending is present. 


Capabilities: "OpenGL" M Direct3D M 
M IS_HARDWARE" 
M TOTAL_VIDEO_MEMORY M 
M FREE_VIDEO_MEMORY" 
M RGB_LIGHTING" 
M ALPHA_BLENDING" 11 Ml P MAP¬ 
PING" M MAX_TEXTURESIZE_X" 
M MAX_TEXTURESIZE_Y" 
M TEXTURE_SQUARE M 
M MAX_LIGHTS" 
M FREE_TEXTURE_MEMORY" 
M TOTAL_TEXTURE_MEMORY M 
"FREE_PHYSICAL_MEMORY 
(KB)" 

"TOTAL_PHYSICAL_MEMORY 

(DB)" 

"USED_PHYSICAL_MEMORY %" 


Example: captest .wrl. All avail¬ 
able browser information is dis¬ 
played in the console, 
returns the string of the directory 
blaxxun Contact resides 


String 

getlnstallDirectory() 
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bool setOption 
(String option, 

String optionValue) 

List of setOption values: 

antiAliasing ("TRUE"/ 
"FALSE") 

collisionDetection("TRUE"/ 
"FALSE") 

dithering ("TRUE"/"FALSE") 

exactCollision ("TRUE"/ 
"FALSE") 

fullscreen ("TRUE"/ 

"FALSE") 

gravity ("TRUE"/"FALSE") 

ISSE ( "TRUE"/"FALSE" ; Kat- 
mai ISSE instructions on/off) 

mipmap ("TRUE"/"FALSE") 

lodScale (float global scale factor 
for visibilityLimit, LOD (same as per¬ 
formance visibilty factor)) 

lightscale (float global scale 
factor for light intensity) 

NurbsTesselationScale (float) 

NurbsTargetFps (float) 


NurbsTessellationMode (int 
NURBS tesselation mode : 

0 S TATIC_TE S S ELATION 

1 DYNAMIC_TESSE LATION 

2 F RAME RATE_T ESSE LATION 

3 

DYNAMIC_FRAMERATE_TESSELAT 

ION) 
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relativeTime ("TRUE"/ 
"false" ) - changes timebase to 
‘relative to the load time of the 
scene’, FALSE seconds since 1970 
(VRML97 notion) 

resetRelativeTime (sets the 
local timebase for relativeMode to 0) 

ref reshTime (sets the Contact 
cache session reference time to 
now) 

smooth ("TRUE"/"FALSE") 

Smooth texture filtering 

soundQuality (int Sound quality 
settings (initial value)) 

soundDopplerFactor (float - 
sets the Direct Sound doppler factor) 

soundRolloffFactor (float - 
sets the Direct Sound rolloff factor) 

soundVelocity (vx vy vz - sets 
the Direct Sound listeners velocity) 

texturing ("TRUE"/"FALSE") 

Texturing enable / disable 


string getOption 
(String option) 


see above list 


Memory Management 
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setUnloadMode 

sets strategy for purging inlines from 

(int minNotActivelnlines, 
float percentageFactor- 
ToPurge) 

memory: 

if the number of inlines currently not 
rendered is greater than minAc- 
tivelnlines, purge up to (number * 
percentage ) inlines from memory 
if percentage < 0 its an absolute 
number of inlines to purge 

int prefetch 
(MFNode argument, 
boolean loadlnlines, 
boolean loadTextures) 

Example: 

setUnloadMode(100,0.05) 

if more than 100 inlines are currently 
not rendered, delete the 5 % of the 
inlines least recently used 
prefetch instructs the browser to 
load the media resources listed in 
argument, parameter 1 and 2 are 
true by default. 

If argument directly references 
ImageTexture, MovieTexture, Inline, 
Script or AudioClip nodes the return 
value is the number of those nodes 
loaded. 

VRML Scene 

Node getScriptO 

returns a SFNode refering to the 
Script node of the script. Often script 
authors need to have a "this" refer¬ 
ence in a Script. The common 
method using an extra SFNode field 
in the Script field list is possible too 
but may result in memory leaks in 
Contact. 

setBspMode(order) 
setBspLoadingMode(order) 

set bsp traversal order 
set bsp inline traversal order 

TRAVERSE_NORMAL 0 

TRAVERSE_BACK_TO_FRONT 1 
TRAVERSE FRONT TO BACK 2 


40 





Scripting 



axxun 


Node computeRayHit 
(SFVec3f startPoint, 
SFVec3f endPoint, 

Node optionalStartingNode) 


Computes an intersection of a ray 
with the scene graph. Result is null if 
no intersection is found otherwise a 
PseudoNode RayHitlnfo with this 
information : 


PROTO RayHitlnfo [ 

eventOut MFNode hitPath 

# the chain of grouping nodes, to the 
geometry node intersected 

eventOut SFVec3f hitNormal 

# normal at point of intersection 

eventOut SFVec3f hitPoint 

# point of intersection in global world 
coordinates 


eventOut SFVec2f hitTexCo- 
ord 

# texture coordinate at point of inter¬ 
section (without any texture matrix 
applied) 

eventOut SFMatrix hitMatrix 

# matrix transforming shape local 
coordinates to world coordinates 

eventOut SFVec3f hitNormalLocal 

eventOut SFVec3f hitPoint- 
Local 

# intersection point in the shapes 
local coordinate system 

eventOut MFInt32 hitlnfo 

# vertex index information 

] 

Example: rayhittest.wri 

Navigate so that an object is in the 
center of the view and click the cylin¬ 
der, information on hit is displayed in 
the console. 
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Node computeCollision 
(SFNode sourceNode(geome¬ 
try) , 

VrmlMatrix sourceMatrix, 
SFNode targetScenegraph, 
VrmlMatrix targetMatrix) 


Computes collision between a 
geometry node and the scene 
graph. Source and targetMatrix 
describe the transformation of 
source respectively SceneGraph. 
Use them for moving systems e.g. 
sourceNode is a (moving) ball and 
sourceMatrix contains the current 
transformation. Result is null if no 
intersection found or a PseudoNode 
Collisionlnfo with the following infor¬ 
mation: 

PROTO Collisionlnfo [ 
eventOut MFNode hitPath 

# the chain of grouping nodes the 
geometry node source collided with 

eventOut SFMatrix hitMatrix 

# matrix transforming local coordi¬ 
nates to world coordinates 

eventOut MFInt32 hitlnfo 

# vertex index information 

] 

Example: collisiontest.wri. 

Click the cylinder, console displays 
collision information. Arguments 2 
..4 are optional, as matrix null value 
can be passed. 

Collision is more performant if matri¬ 
ces do contain only uniform scale. 
All Contact space subdivision 
techiques like Groups with bbox- 
size and BspTree are fully 
exploited for speedup if used in the 
target scene graph. 


Browsers object properties 

The Browser object itself is a VRML node with certain events and fields. By add 
ing ROUTES from vrmlscript or eventOut Observers from the EAI, these events 
can be observed. 
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Access from vrmlscript: Browser .xxx 
Access from EAI: Browser .getEventln (xxx) 
Browser.getEventOut(xxx) 


Avatar 

eventIn MFNode 

set my avatar nodes (for a 

set_myAvatarNodes 

createVrmIFromURL callback) 

eventln SFString 

sets my avatar URL 

set myAvatarURL 

eventln SFString 

set my avatar nickname 

set myAvatarName 

eventln SFBool 

toggle third-person mode 

set showMyAvatar 

exposedField SFString 

current avatar URL 

myAv a t a rUR L 

exposedField SFNode 

the bound (displayed) avatar node 

boundAvatar 

(may contain wrapper around myAv- 

exposedField SFNode 

atarUrl) 

node currently used as myAvatar 

myAvatar 

node 

exposedField SFString 

current avatar nickname 

myAvatarName 

exposedField SFVec3f 

x,y,z relative translation distance for 

followDolly 

third-person view 

exposedField SFVec3f 

x,y rotation value for third person 

followOrbit 

viewing mode 

exposedField SFVec3f 

x,y pan rotation value for third per¬ 

followPan 

son viewing mode 


Viewpoint 

eventOut SFVec3f 

global viewer postion 

viewpointPosition 

eventOut SFRotation 

global viewer orientation 

viewpointOrientation 
exposedField MFNode 

complete list of Viewpoints 

viewpoints 
exposedField SFNode 

the currently bound viewpoint (top of 

boundViewpoint 

stack) 





Scripting - Scripting extensions 


exposedField MFNode 
boundViewpointStack 


the other stacked viewpoints (if any) 



Navigation 

exposedField SFNode 
boundNavigationlnfo 
exposedField MFNode 
boundNavigationlnfoStack 


the currently bound navigation info 
the other stacked Navigationlnfos 


Fog 

exposedField SFNode 
boundFog 

exposedField MFNode 
boundFogStack 


Background 

exposedField SFNode 
boundBackground 
exposedField MFNode 
boundBackgroundStack 


the currently bound fog 
the other stacked Fog nodes 


the currently bound Background 
node 

the other stacked Background 
nodes 


VRML Browser window 

eventout SFVec2f windowsize rendering window width and height 
eventout SFFloat aspect ratio of rendering window 

windowAspect 


VRML Browser 

exposedField SFString name Browser name 
exposedField SFString Browser version 

version 
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Scripting 


VRML world 

exposedField SFString 
worldUrl 

exposedField MFNode 
overTouchSensors 
exposedField MFNode 
activeVisibilitySensors 

exposedField MFNode 
protoScenes 
exposedField MFNode 
foreground 
eventOut SFTime 
time_changed 


URL of the currently loaded world 
(set observer to get a world changed 
notification) 

list of TouchSensors the mouse is 
over 

list of VisibilitySensors and Occlu¬ 
sion nodes currently assumed to be 
visible 

list of scenes with prototypes 
(loaded via EXTERNPROTO URL..) 
additonal set of nodes rendered 
after scene 
the master clock 


Extensions to field objects object 

Methods 

string getTypeO returns the type of the field as VRML 

fieldType name 

string toStringO converts the field to its VRML string 

representation. 





Scripting - Scripting extensions 


Extensions to vrmlscript SFNode object 


Methods 

string getType() 

returns the type of the node as 

VRML nodeType or prototype name 

string getName() 

returns the nodes DEF name if avail¬ 
able. The node name is not avaible if 
the node is part of a PROTO and the 
node in this instance was copied. 

node copy() 

creates a copy of the node (no deep 
copy on SFNode / MFNode fields is 
done) 

object getEventln 
(string eventInName) 

boolean hasEventln 
(string eventName) 
object getEventOut 
(string eventOutName) 

boolean hasEventOut 
(string eventName) 
VrmlMatrix getMatrixO 

get eventln object of Node 

returns true if Node has an eventln 
named eventName 

get eventOut object of Node 

returns true if Node has an eventOut 
named eventName 

returns Matrix of Transform, Matrix- 
Transform or last Matrix of HUD, Bill¬ 
board or related VRML 1.0 nodes 

boolean setMatrix 
(vrmlMatrix) 

sets Matrix of Transform or Matrix- 
Transform nodes, returns false if 
matrix can not be set. 

MFVec3f getBBox() 

returns the bounding box of the 
node, return value [0] contacins the 
min position, value[1] the max posi¬ 
tion. The function is optimized if 
called for a Geometry node. 


Extensions to vrmlscript MFTime object 

supports the same members and methods as MFFIoat object, but values are 
stored in double precision. 
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Extensions to vrmlscript MFVec3f object 


Scripting 



This assignment function performs a 
series of transformations to coordi¬ 
nates in srcPoints and assigns the 
result to the object. The operation is 
comparable to a nested Transform 
scene graph used to animate a hier¬ 
archical model like an Avatar. 

The last 5 parameters can be omit¬ 
ted, in order to speed up the opera¬ 
tion. If there are n groups of vertices 
to transform, length of srclndex must 
be n*3 and the length of each trans¬ 
formation data array must be at least 
n or 0. 

The operation expressed in pseudo code: 

VrmlMatrix matrixStack[]; 
var index; 

for( index=0; index<srclndex.length/3; index+=l) 

{ // for all indices in groups by 3 

var level=srclndex[index*3];// get the nesting level 
var startlndex=srclndex[index*3+l]; // start vertex index 
var endlndex=srclndex[index*3+2]; // end vertex index 

// compute transformation, right most arguments can be omitted 
// for speed 

matrixStack[level]=m.setTransform(translation[index], 
rotation[index], scaleFactor[index],scaleOrientation[index], 
center[index]) ; 

if (level!=0) { 

matrixStack[level].MultiplyRight( matrixStack[level-1]); 

// combine with parent 

} 

for(var i=startlndex;i<endlndex;i++){ 

// transform the Vec3f subset 

this[i] = matrixStack[level] * srcPoints[i]; 

} 

} 


setByVertexTransform 
(MFVec3f srcPoints, 
MFInt32 srclndex, 

MFVec3f translation, 
MFRotation rotation, 
MFVec3f scale, 

MFRotation scaleOrienta¬ 
tion, 

MFVec3f center) 


blaxxun 
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Scripting - Scripting extensions 


MFVec3f getBBox () returns the bounding box of the 

array of Vec3f, return value [0] 
returns the min position, value[1 ] the 
max position. 






Scripting 


blaxxun 


Extensions to vrmlscript Math object 


double atan2 
(double dy, double dx) 
double cosh(double x) 
double sinh(double x) 
double tanh(double x) 

double randomGaussian() 
double noise(double x) 


arc tangent -PI .. PI 

computes the hyperbolic cosine of x 
computes the hyperbolic sine of x 
computes the hyperbolic tangent of 
x 

gaussian random number-1 ..1 
evaluates solid noise function on x 


Extensions to vrmlscript SFString object 

int getCharCodeAt (index) returns the character code as inte¬ 
ger at position index 

string f romCharCode (inti , constructs and returns a new string 
.... intn) composed of the given sequence of 

character codes 


Extensions to vrmlscript SFImage object 


SFImage new SFImage 
(int width,int height, 
int componenents, 
MFFloat pixels) 


constructs SFImage using a float 
array of length widht*height*compo- 
nents. This function can be used to 
avoid the time consuming pixel 
packing in vrmlscript for dynamically 
computed SFImage objects. 


Extensions to vrmlscript MFNode object 


boolean add(SFNode node) adds a single SFNode to the field, 
boolean remove (SFNode node) removes a single SFNode to the 

field. 


int find(SFNode node) 


returns the index of a node in field, 
-1 if not found. 


SFNode returns the first node with a match- 

findByName (string name) ing name, null if not found. 
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Scripting - Scripting extensions 





^ ^ blaxxun 

Extensions 


Node Extensions 

blaxxun Contact 3D supports several VRML extensions. These extension nodes 
are not available for blaxxun3D. 

Please note that as no testing suites are available for blaxxuns extension 
nodes, blaxxun does not claim to fully support those nodes (though we 
think we do). Most of these nodes are proposed as VRML 97 amendments 
to the Web3d consortium, so their implementation is subject to change 
(with the standardization process). You should use these nodes only if 
they are useful or needed for your project. 

The following nodes are currently considered as a beta implementation: 
Drag & Drop Sensor, MultiTexturing, Particle Systems. 

CompositeTexture3D and subdivisions have alpha status. 

The following nodes should NOT be used anymore as further development 
is discontinued and Contact 5.0 provides better alternatives: 

Observing Mouse and Keyboard Input with an EventObserver (replaced by 
DeviceSensor), 

HUD replaced by Layer3d and Layer2d. 

For broadest compatibility to the VRML specification these extensions should 
not be used until required for a specific problem solution. Often scripting code 
can be made compatible by using extensions only in javascript code branches 
checking first for Browser. getName () & parseFloat (Browser . getVer- 
sion()) . 


Extensions nodes are native implemented EXTERNPROTO’s. For VRML 97 
conformance, a PROTO definition for the extension node should be added in the 
following way 

EXTERNPROTO ExtensionNode[ 

#fields, eventlns and eventOuts of that node 
] 

["urn:inet:blaxxun.com:node:ExtensionNode", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#ExtensionNode"] 

If possible nodes have an usefull fallback implementation. 
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Extensions - Node Extensions 


All built-in nodes can be referenced using the EXTERNPROTO URN syntax 
"urn: inet: blaxxun. com: node: NodeType ", the interface of the native 
node is used, not the interface of the EXTERNPROTO statement. 

Contact parses PROTO, ROUTES, EXTERNPROTO in all places a node value 
is expected 


Background2D 

Introduction 

MPEG4 Node. This node is not supported in the current version of blaxxun 

Contact. It is meant for future release. 

The Background2D node allows a background to be displayed behind a 2D 

scene. The functionality of this node can also be accomplished using other 

nodes, but use of this node may be more efficient in some implementations. 

Node definition 

Background2D{ 

eventln SFBool set_bind 
exposedField SFColor backColor 000 
exposedField MFString url [] 
eventOut SFBool isBound 

} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Background2D[ 
eventln SFBool set_bind 
exposedField SFColor backColor 
exposedField MFString url 
eventOut SFBool isBound 

] 

["urn:inet:blaxxun.com:node:Background2D", 

"http://www.blaxxun.com/protos/nodes.wrl#Background2D"] 


Field description 


set bind 
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backColor 


eventln to move this Background 
node on top of the Background node 
stack 

specifies a colour to be used as the 
background 






url 

isBound 


specifies the data source to be used 
TRUE if node is top of the stack, 
FALSE if removed from the stack 


Extensions 



axxun 


Bitmap 


Examples 

no examples available yet. 


Introduction 

MPEG4 Node. This node is not supported in the current version of blaxxun 
Contact. It is meant for future release. 

Bitmap is a geometry node centered at (0,0) in the local coordinate system, to 
be placed in the geometry field of a Shape node. It is a screen-aligned rectangle, 
which means that the surface normal of this rectangle will always be in the same 
direction as the screen surface normal, namely straight out to the viewer. It is for 
example not possible to view the Bitmap under an angle from the side. Bitmap 
has the dimensions of the texture that is mapped onto it, as specified in the 
Appearance node of its parent Shape node. However, the effective geometry of 
Bitmap is defined by the non-transparent pixels of the image or video that is 
mapped onto it. When no scaling is specified, a trivial texture-mapping (pixel 
copying) is performed. 

Bitmap shall not be rotated but may be subject to translation. 

Geometry sensors shall respond to the effective geometry of the Bitmap, which 
is defined by the non-transparent pixels of the texture that is mapped onto it. 


Node definition 


Bitmap{ 


exposedField SFVec2f scale -1 -1 

} 

For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Bitmap[ 

exposedField SFVec2f scale 

] 


Bitmap 


["urn:inet:blaxxun.com:node:Bitmap", 

"http://www.blaxxun.com/protos/nodes.wrl#Bitmap"] 
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Extensions - Node Extensions 


Field description 

scale The scale field specifies a scaling of 

the geometry in the x and y dimen¬ 
sions, respectively. 

The scale values shall be strictly 
positive or equal to -1. A scale value 
of -1 indicates that no scaling shall 
be applied in the relevant dimension. 
The special case where both scale 
dimensions are-1 indicates that the 
natural dimensions of the texture 
that is mapped onto the Bitmap shall 
be used. 


Examples 

no examples available yet. 


BSPTree 


blaxxun Contact 3D supports a BspTree node for optimal rendering performance 
of large worlds. For technical information beyond the following paragraphs you 
may also see the chapter “Render Culling and BSP-Tree Optimization” on page 
226 

Introduction 

The handling of large worlds is currently not well supported by VRML 2.0 brows¬ 
ers. Browsers could implement view culling using bounding box information 
stored in Group nodes, but typical scenes are not well spatial organized for this 
optimization. Even then a large amount of invisible geometry needs to be 
checked and passed to the rendering subsystem. 

A common solution used in games is to subdivide the world into smaller parts, 
where the browser can quickly decide to draw or not to draw a part. One method 
is the Binary Space Partitioning Tree (BSP-Tree). Here the world is divided by 
an infinite plane into the parts in front and behind the plane. The remaining parts 
themselves are recursively split until each part is a single object. 

In a true BSP-Tree, which can be rendered without the help of a z-buffer, each 
object is a single polygon. A polygon might get split if it crosses the plane of its 
parent tree node, a node stores also the list of polygon exactly on the plane. 






bined with dynamic, moving parts that are not part of the BSP-Tree hierarchy. 
Here z-buffering is enabled, to ensure correct visibility. 

blaxxun Contact supports this technique by the following ExtensionNode: 

Node definition 

BspTree{ 

exposedField SFRotation plane 0010 
exposedField SFNode front NULL 
exposedField SFNode overlap NULL 
exposedField SFNode back NULL 

} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO BspTree [ 

exposedField SFRotation plane 
field SFNode front 
field SFNode overlap 
field SFNode back 

] 

["urn:inet:blaxxun.com:node:BspTree", 

"http://www.blaxxun.com/protos/nodes.wrl#BspTree" ] 


blaxxun 
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Extensions - Node Extensions 


Fields description 

plane 


encodes the splitting plane of this 
node in standard form : 


plane[0] *x + plane[1 ] *y + plane[2] *z 
+ plane[3] == 0 


front 


is the scene graph totally in the front 
(or in touch) with the plane 


back 


is the scene graph totally in the back 
(or in touch) with the plane 


overlap 


is the scene graph on the plane 
(True BSP Mode) or which has parts 
on both sides of the plane (hybrid 
BSP mode) 


Examples 

Examples for a generated outdoor grid environment: 

Grid size 64*64 = 4096 objects 

standard VRML97 version (Warning: some VRML browser may have problems 
with this) 

blaxxun Contact 3D BspTree version 


BSPGroup 


Introduction 

The BSPGroup is a simplified approach of the BSPTree. The BspGroup speci¬ 
fies as children a list of nodes, where automatically a BspTree 

is constructed. A Group with a big list of static children could simply be replaced 
by a BspGroup node. 

Node definition 

BspGroup{ 

field SFVec3f bboxSize -1 -1 -1 
field SFVec3f bboxCenter 000 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventIn MFNode removeChildren 
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Extensions 



axxun 


Camera 


eventOut SFNode bspTree # access to the created BspTree 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO BspGroup[ 

field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField MFNode children 
eventln MFNode addChildren 
eventIn MFNode removeChildren 

eventOut SFNode bspTree # access to the created BspTree 
hierarchy 
] 

["urn:inet:blaxxun.com:node:BspGroup", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#BspGroup"] 

Field description 

bboxSize defines the bounding box of the 


BSPGroup, important for better cull¬ 
ing 

center of the bounding box 
children geometry 
eventln for adding children 
eventln for removing children 
eventOut that returns the created 
BSPTree as a SFNode 


bboxCenter 

children 

addChildren 

removeChildren 

bspTree 


Examples 

see “BSPTree” on page 54 for examples 


Introduction 

The Camera node enables content authors to design their own navigation. See 
also “Generic Input Handling” on page 202 for details on that. 

All standard modes like WALK, SLIDE, PAN, FLY are realized by applying differ¬ 
ent values to the ypr (yaw,pitch,roll) and the xyz field. 


Camera 
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Extensions - Node Extensions 


Node definition 


Camera { 

eventln SFBool set_bind 
eventln SFVec3f xyz 
eventln SFVec3f ypr 
eventln SFVec2f yp 
eventln SFVec3f moveTo 
eventln SFVec3f orientTo 
eventln SFVec3f examineCenter 
eventln SFBool straighten 
exposedField SFTime duration 0 
exposedField SFInt32 examineRadius 0 
exposedField SFVec3f offset 000 
exposedField SFBool collide TRUE 
exposedField SFBool gravity TRUE 
field SFString description "" 
field SFVec3f upVector 010 
eventOut SFRotation orientation 
eventOut SFVec3f position 
eventOut SFTime bindTime 
eventOut SFBool isBound 

} 

} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 


EXTERNPROTO Camera[ 

eventln SFBool set_bind 
eventln SFVec3f xyz 
eventln SFVec3f ypr 
eventln SFVec2f yp 
eventln SFVec3f moveTo 
eventln SFVec3f orientTo 
eventln SFVec3f examineCenter 
eventln SFBool straighten 
exposedField SFTime duration 
exposedField SFInt32 examineRadius 
exposedField SFVec3f offset 
exposedField SFBool collide 
exposedField SFBool gravity 
field SFString description 
field SFVec3f upVector 
eventOut SFRotation orientation 
eventOut SFVec3f position 
eventOut SFTime bindTime 
eventOut SFBool isBound 
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] 






Extensions 


blaxxun 


[ "urn:inet:blaxxun.com:node:Camera", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Camera" ] 


Field description 


set_bind 

ypr 


xyz 

yp 

moveTo 

orientTo 

examineCenter 


straighten 

duration 

examineRadius 


eventln to “activate” this Camera 
the ypr field is the angular speed in 
radians per second 
(yaw around the y-axis, pitch around 
the x-axis, roll around the z-axis). 
specifies the speed in m/s 
angular speed 

If a moveTo eventln is received, the 
camera animates to the point in 
duration seconds. 

If a orientTo eventln is received the 
camera turns to the given point in 
duration seconds. 

defines the center of a virtual sphere 
on which the camera is moved with 
yp angular velocity. 

If no examineCenter is set (exami¬ 
neCenter 0 0 0) the browser inple- 
mentation should calculate a suit¬ 
able value e.g. the centre of the 
scene bounding box. Note that the 
camera target (look-at point) is not 
changed, i.e. the viewer moves on 
the virtual sphere, but does not look 
to the center automatically, 
corrects the camera orientation 
along the upVector 
animation time in seconds, used 
together with moveTo and orientTo 
events 

distance between viewer and exam¬ 
ineCenter. 
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Extensions - Node Extensions 


offset 


collide 

gravity 


description 

upVector 

orientation 

position 

bindTime 

isBound 


additional offset applied to the cur¬ 
rent camera position and orientation. 

Further movements are always 
applied to the actual position without 
the offset. The value is specified in 
spherical coords with the first value 
as radius, second and third value as 
angles. 

The collide field sets the collision 
detection of the browser. 

If the gravity field is set to TRUE, the 
built-in ground detection is enabled. 
To detect the ground, a ray hit test is 
performed with a ray defined by the 
down vector. Thus velocity vectors 
in opposite direction of the down- 
vector are disregarded, 
description of that Camera, shown in 
the browser status bar 
upVector of the camera 
orientation of the camera 
position of the camera 
time at which the Viewpoint node is 
bound or unbound 
sends TRUE when Viewpoint is put 
to the top of the viewpoint stack, 
FALSE if removed from the stack 


Note that the speed vectors(xyz, ypr) are applied to the local coord system of the 
bound viewpoint. Navigationlnfo node values(e.g. the speed and type) are 
replaced by the respective Camera node valuies. 

Examples 

please see “Generic Input Handling” on page 202 


Cell 


Introduction 

Cells & Portals allows the visibility management of complex indoor environ¬ 
ments.For further details, please also read the documentation at "Cells&Por- 
tals" on page 234 





Extensions 



The Cells and Portals technique combines several extension nodes. Please see 
also the node definitions for “CellGroup” on page 62 and “Portal” on page 103 


Node definition 


Cell { 

exposedField 

exposedField 

exposedField 

eventIn 

eventIn 

exposedField 

exposedField 

} 


SFVec3f bboxSize -1 -1 -1 
SFVec3f bboxCenter 000 
MFNode children [] 

MFNode addChildren 
MFNode removeChildren 
MFNode portals 
SFInt32 content 0 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 


EXTERNPROTO Cell[ 
exposedField 
exposedField 
exposedField 
eventIn 
eventIn 
exposedField 
exposedField 


SFVec3f bboxSize 
SFVec3f bboxCenter 
MFNode children 
MFNode addChildren 
MFNode removeChildren 
MFNode portals 
SFInt32 content 


["urn:inet:blaxxun.com:node:Cell", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Cell"] 


Field description 


bboxSize 

bboxCenter 

children 

addChildren 

removeChildren 

portals 

content 


size of the bounding box 
bbox center 

all nodes being part of the cell 
eventln for adding children 
eventln for removing children 
specifies the list of Portals for the 
Cell 

The content field is for application 
use. A possible use is to define con¬ 
tent types like water, closed space, 
normal space having different mean¬ 
ing of the application, (e.g. User can 
not walk into a Cell containing 
water.) 


blaxxun 
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Extensions - Node Extensions 


Examples 

8*8 script generated in-door scene 

16*16 script generated out-door scene (with visibilityLimit) 

The culling rate can be observed using the F8 keys, the last number represents 
the number of primitives (IndexedFaceSet’s) after all culling. (ViewFrustrum,Cell 
& Portal culling.) 

Please see the chapter “Cells&Portals” on page 234 for more details and exam¬ 
ples 


CellGroup 


Introduction 

Cells & Portals allows the visibility management of complex indoor environ¬ 
ments.For further details, please also read the documentation at "Cells&Por- 
tals" on page 234 

The Cells and Portals technique combines several extension nodes. Please see 
also the node definitions for “Cell” on page 60 and “Portal” on page 103 


Node definition 


CellGroup[ { 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
eventIn 
eventIn 
eventOut 

} 


SFVec3f bboxSize -1 -1 -1 
SFVec3f bboxCenter 000 
SFInt32 range -50 
MFNode cells [] 

MFNode children [] 

MFNode addChildren 
MFNode removeChildren 
MFNode activeCells 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 


EXTERNPROTO CellGroup[ 


exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

eventIn 

eventIn 


SFVec3f bboxSize 
SFVec3f bboxCenter 
SFInt32 range 
MFNode cells 
MFNode children 
MFNode addChildren 
MFNode removeChildren 
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Extensions 



eventOut MFNode activeCells 

] 

["urn:inet:blaxxun.com:node:CellGroup", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#CellGroup"] 

Field description 


bboxSize 

bboxCenter 

range 


cells 


children 


addChildren 

removeChildren 

activeCells 


size of the bounding box 
bbox center 

allows to limit the cell recursion 
depth. The Cell tree is recursivley 
traversed up to the level abs(range). 
If range is negative the browser can 
automatically lower the range 
depending on system performance, 
specifies the list of cells composing 
the CellGroup. The nodes must be 
Cell nodes. 

may specify a list of children nodes 
consisting out of a BspTree Tree 
with Cell nodes as leaves. Nodes 
contained in the children field are not 
rendered in a linear way, they are 
used to find the initial starting cell, 
the cell containing the current view¬ 
point. 

eventln for adding nodes to the chil¬ 
dren field 

eventln for removing nodes from the 
children field 

activeCells eventOut is set to the list 
of currently visible cells, active- 
Cells[0] is the starting cell, which 
contains the viewer. 


Examples 

8*8 script generated in-door scene 

16*16 script generated out-door scene (with visibilityLimit) 

The culling rate can be observed using the F8 keys, the last number represents 
the number of primitives (IndexedFaceSet’s) after all culling. (ViewFrustrum,Cell 
& Portal culling.) 


blaxxun 
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Extensions - Node Extensions 


Please see the chapter “Cells&Portals” on page 234 for more details and exam 
pies 


Coordinatelnterpolator2D 


Introduction 

MPEG4 Node. This node fills the lack of the missing 2D Interpolators in the 

VRML97 Spec. The node works like a common Coordinatelnterpolator with the 

difference of the keyValues being multiple SFVec2f values. 

Node definition 

CoordinateInterpolator2D { 

eventln SFFloat set_fraction 
exposedField MFFloat key [] 

exposedField MFVec2f keyValue [] 

eventOut MFVec2f value_changed 

} 

For Compatibility with other VRML97 Browsers you should implement the node 

as an EXTERNPROTO using the following syntax. 

EXTERNPROTO CoordinateInterpolator2D[ 
eventln SFFloat set_fraction 
exposedField MFFloat key 

exposedField MFVec2f keyValue 

eventOut MFVec2f value_changed 


["urn:inet:blaxxun.com:node:CoordinateInterpolator2D", 
"http://www.blaxxun.com/vrml/protos/ 
nodes.wrl#CoordinateInterpolator2D"] 

Field description 


key 

keyValue 

value_changed 


set fraction 


receives an SFFloat event and 
causes the interpolator function to 
evaluate 

Interpolation values 
corresponding values to key 
interpolated value 
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Examples 

no examples available. 






CompositeTexture3D 


Extensions 



Introduction 

MPEG4 Node.This node allows to render a subscene dynamically to a texture. 
It can only be used as a texture field of an Appearence node. 

Please see also the chapter “Multitexturing” on page 210 

Node definition 


CompositeTexture3D{ 

exposedField SFInt32 pixelWidth -1 
exposedField SFInt32 pixelHeight -1 
exposedField SFNode background NULL 
exposedField SFNode fog NULL 
exposedField SFNode navigationlnfo NULL 
exposedField SFNode viewpoint NULL 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventln MFNode removeChildren 

} 

For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO CompositeTexture3D[ 

exposedField SFInt32 pixelWidth 
exposedField SFInt32 pixelHeight 
exposedField SFNode background 

exposedField SFNode fog 

exposedField SFNode navigationlnfo 

exposedField SFNode viewpoint 

exposedField MFNode children 

eventln MFNode addChildren 
eventln MFNode removeChildren 


["urn:inet:blaxxun.com:node:CompositeTexture3D", 
"http://www.blaxxun.com/vrml/protos/ 
nodes.wrl#CompositeTexture3D"] 


Field description 


pixelWidth 


pixelHeight 



specify the ideal width in pixels of 
this map 

specify the ideal height in pixels of 
this map 


blaxxun 
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Extensions - Node Extensions 


fog 

navigationlnfo 
viewpoint 


background 


addChildren 


removeChildren 


children 


Background node used for the Com- 
positeTexture. 

Fog of mapped 3D scene 
Navigationlnfo of mapped 3D scene 
Viewpoint though which the scene is 
rendered 

list of 3D root and children nodes 
that define the 3d scene that forms 
the texture map. 

eventln to add children nodes to the 
projected scene 

eventln to remove children nodes 
from the projected scene 


Implementation Notes 

Behaviors and user interaction are enabled with CompositeTexture3D. How¬ 
ever, no user navigation is possible on the textured scene and sensors contained 
in the scene which forms the CompositeTexture3D shall be ignored. 

CompositeTexture3D is supported by software and most hardware drivers. 
CompositeTexture3D depends on size and number of node instances and can 
use a lot of video memory resources. You should take care to ensure enough 
video memory is available. 

CompositeTexture3D is not supported in the OpenGL version. 

Examples 

no examples available yet. 


CullGroup 


Introduction 

Cullgroup is a group with an automatic bounding box computation for the chil¬ 
dren scene graph. Usefull for early render culling of complex scene graphs (e.g. 
Avatars) 

Node definition 

CullGroup { 

field SFVec3f bboxSize -1 -1 -1 
field SFVec3f bboxCenter 000 
exposedField MFNode children [] 
eventln MFNode addChildren 






eventln MFNode removeChildren 


Extensions 
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For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO CullGroup[ 
field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 
] 

["urn:inet:blaxxun.com:node:CullGroup", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#CullGroup"] 

Field description 

The fields are the same as in a common Group node. See the VRML97 Spec for 
details. 

Examples 

no examples available yet. 


Curve2D 


Introduction 

MPEG4 Node. This node is not supported in the current version of blaxxun 
Contact. It is meant for future release. 

This node is used to describe the Bezier approximation of a polygon in the scene 
at an arbitrary level of precision. It behaves as other "lines", which means it is 
sensitive to modifications of line width and "dotted-ness", and can be filled or not. 

The given parameters are a control polygon and a parameter setting the quality 
of approximation of the curve. Internally, another polygon of fineness points is 
computed on the basis of the control polygon 

Node definition 

Curve2D{ 

exposedField SFNode point NULL 
exposedField SFFloat fineness 0.5 
exposedField MFInt32 type [] 
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For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Curve2D[ 

exposedField SFNode point 
exposedField SFFloat fineness 
exposedField MFInt32 type 

] 

["urn:inet:blaxxun.com:node:Curve2D", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Curve2D"] 


Field description 


point shall list the vertices of the control 

polygon. 

fineness The fineness parameter is an 

SFFloat value that indicates how 
finely to tessellate the Bezier curves. 
A value of 1 means that the curve 
shall be fine enough that no edges 
are visible. A value of 0 indicates 
that a straight line shall be drawn 
between the two points of the curve. 
The default value of 0.5 gives an 
intermediate level of smoothness 

type When the field type is specified, the 

above functionality is extended as 
follows: the curve is now defined 
piecewise either with the above 
equation or as straight segments or 
as non-segments, depending on the 
values in type. 

0 = MoveTo 

1 = LineTo 

2 = CurveTo 

3 = NextCurveto 


Examples 

no examples available yet. 
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DeviceSensor 


Introduction 

The DeviceSensor node observes arbitrary input devices such as a six degrees- 
of-freedom mouse or a speech recognition system, but certainly also standard 
input devices like mouse or keyboard. The device data is wrapped in an Event 
node (already suitable for many possible event types). Special purpose devices 
may replace the default implementation with their own Event node, guaranteeing 
maximum flexibility for all possible input devices. 

Node definition 

DeviceSensor { 

exposedField SFBool enabled TRUE 
exposedField SFString device "STANDARD" 
exposedField SFString eventType "all" 
eventOut SFNode event 
eventOut SFBool isActive 


Field description 


device 


enabled 


defines the state of the DeviceSen¬ 
sor 

defines the device, that should be 
observed by this DeviceSensor, 
possible options are: 


‘STANDARD”, “JOYSTICK”, 
‘SPACEMOUSE” 


optionally a number can be set if 
more than one devices of the same 
kind are available, e.g. “JOYSTICK 


2 ” 


It is also possible to fetch other input 
devices, if the appropriate device 
driver is implemented as a plugin for 
blaxxun Contact 
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eventType 


event 


isActive 


Examples 


defines the eventType of the device, 
which should be observed. If set to 
one certain option, only events of 
that type are delivered. Possible 
options of the standard device 
(mouse/keyboard) are: 

"all", "mouseup", “mousedown", 
“mousemove”, “drop", "mouse- 
wheel", "keydown", "character", 
"keyup", "drop" 

The eventType is dependent from 
the device, e.g. the eventTypes for a 
joystick are different to the ones of 
the standard input. 
eventOut that returns the appropri¬ 
ate event from the device. See 
“Event” on page 71 node for details 
eventOut that sends the activity 
state 


please see “The proto can be configured to the needs of the scene by assigning 
appropriate values to its fields. These fields are described in the table below” on 
page 192 


DrawGroup 

Introduction 

DrawGroup allows the content author to influence transparency processing. 
Wrapping a set of geometry into DrawGroup processes any geometry (even 
transparent ones) in the exact order given by children. This can be used for mir 
ror like effects or to turn off delayed alpha blending for sets of geometry with bi 
level transparency only. Node definition 


DrawGroup{ 

exposedField SFVec3f bboxSize -1 -1 -1 
exposedField SFVec3f bboxCenter 000 
exposedField SFBool sortedAlpha TRUE 
exposedField MFNode drawOp [] 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventIn MFNode removeChildren 
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For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO DrawGroup[ 

exposedField SFVec3f bboxSize 
exposedField SFVec3f bboxCenter 
exposedField SFBool sortedAlpha 
exposedField MFNode drawOp 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 

] 

["urn:inet:blaxxun.com:node:DrawGroup", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#DrawGroup"] 


Field description 


bboxSize 

bboxCenter 

sortedAlpha 

drawOp 

children 

addChildren 

removeChildren 


size of bounding box 
center of bounding box 

net yet supported 
list of 3D nodes, which are pro¬ 
cessed in the exact given order 
eventln for adding children 
eventln for removing children 


Examples 

no examples available yet. 


Introduction 

The Event node is a speciality in this list of nodes, because it is not used as a 
node in the scene graph. Instead it is returned by eventOut of Sensors such as 
the DeviceSensor. This node is modelled after the W3C-DOM Events. For fur¬ 
ther details on this, please also read this specification. 

Node definition 

Event { 

eventln SFBool cancelBubble 
eventOut SFString type 
eventln SFBool returnValue 
eventOut SFVec2f screen 


blaxxun 
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eventOut 

eventOut 

eventOut 

eventOut 

eventOut 

eventOut 

eventOut 

eventOut 

eventOut 

eventOut 

eventOut 

} 


SFVec2f client 
SFVec2f position 
SFVec3f xyz 
SFVec3f ypr 
SFBool altKey 
SFBool ctrlKey 
SFBool shiftKey 
SFInt32 keyCode 
SFString dataType 
SFString data 
SFInt32 button 


Note: This Node is not referred as EXTERNPROTO, due it is not added to the 
scenegraph. 

Field description 


cancelBubble 


type 

returnValue 


screen 


client 

position 

xyz 

ypr 

altKey 


The cancelBubble property controls 
the bubbling phase of the event flow. 
If the property is set to true, the 
event ceases bubbling at the current 
level. If the property is set to false, 
the event bubbles up to its parent. 
The default value of this property is 
determined by the event type. 

The type property represents the 
event name as a string property. 

If this changed to FALSE, the event 
is no more propagated to other 
DeviceSensors, Mouse-/KeySen- 
sors, or Contacts built-in handler, 
screen.x indicates the horizontal 
coordinate at which the event 
occurred relative to the origin of the 
screen coordinate system, screen.y 
the vertical coordinate, 
the mouse coordinate in pixels 
the mouse coordinate normalized to 
[- 1 -.+ 1 ] 


indicates whether the ’Alt’ key was 
pressed during the firing of the 
event. 
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ctrlKey 

indicates whether the 'Ctrl' key was 
pressed during the firing of the 
event. 

shiftKey 

indicates whether the shift key was 
pressed during the firing of the 
event. 

keyCode 

For key events keyCode holds the 
virtual key code of the key which was 
pressed. For non key events the 
value is zero. Currently the raw 

Win32 keycode is reported. 

dataType 

the type of a dropped item after a 
drag & drop action, (only valid for 
"drop"-events) 

data 

the URL, file name or data itself after 
a drag & drop action, (only valid for 
"drop"-events) 

button 

is used to indicate which mouse but¬ 
ton changed state. This is a bitmask 
with the values 1 for left button, 2 for 
right and 4 for middle. 


Possible event types, that may be received as string in the field “type”: 


click 

The click event occurs when the 
pointing device button is clicked over 
an element. This attribute can be 
used with most elements. 

dblclick 

Bubbles: Yes 

Cancellable: Yes 

Context Info: screen, client, position, 
altKey, ctrlKey, shiftKey, button 

The dblclick event occurs when the 
pointing device button is double¬ 
clicked over an element. This 
attribute can be used with most ele¬ 
ments. 

Bubbles: Yes 

Cancellable: Yes 

Context Info: screen, client, position, 
altKey. ctrlKey. shiftKey. button 
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mousedown 

The mousedown event occurs when 


the pointing device button is pressed 
over an element. 

mouseup 

Bubbles: Yes 

Cancellable: Yes 

Context Info: screen, client, position, 
altKey, ctrlKey, shiftKey, button 

The mouseup event occurs when 
the pointing device button is 
released over an element. 

mouseover 

Bubbles: Yes 

Cancellable: Yes 

Context Info: screen, client, position, 
altKey, ctrlKey, shiftKey, button 

The mouseover event occurs when 
the pointing device is moved over an 
element. 

mousemove 

Bubbles: Yes 

Cancellable: Yes 

Context lnfo:screen, client, position, 
altKey, ctrlKey, shiftKey 

The mousemove event occurs when 
the pointing device is moved while it 
is over an element. 

mouseout 

Bubbles: Yes 

Cancellable: No 

Context lnfo:screen, client, position, 
altKey, ctrlKey, shiftKey 

The mouseout event occurs when 
the pointing device leaves an ele¬ 
ment. 

Bubbles: Yes 

Cancellable: Yes 

Context Info: screen, client, position, 
altKey, ctrlKey, shiftKey, button 
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keypress 


keydown 


keyup 


resize 


Examples 

please see Genereic Input Handling 


The keypress event occurs when a 
key is pressed or released. 

Bubbles: Yes 

Cancellable: Yes 

Context Info: keyCode, charCode 

The keydown event occurs when a 

key is pressed. 

Bubbles: Yes 

Cancellable: Yes 

Context Info: keyCode, charCode 

The keyup event occurs when a key 

is released. 

Bubbles: Yes 
Cancellable: Yes 
Context Info: keyCode, charCode 
The resize event occurs when a doc¬ 
ument is resized. 

Bubbles: Yes 
Cancellable: No 
Context Info: None 


examples of usage of the Event Node. 


Introduction 

Fog2 is like fog with the additional parameter visiblityStart for linear fog. As 
Direct3D does not support exponential fog, linear fog starts per default at 0 in 
VRML often causing too early blending with the fog color. 

Node definition 

Fog2 { 

exposedField SFColor color 111 
exposedField SFString fogType "LINEAR" 
exposedField SFFloat visibilityRange 0 
exposedField SFFloat visibilityStart 0 
exposedField SFFloat density 1 
eventln SFBool set_bind 
eventOut SFBool isBound 
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For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Fog2[ 
exposedField SFColor color 
exposedField SFString fogType 
exposedField SFFloat visibilityRange 
exposedField SFFloat visibilityStart 
exposedField SFFloat density 
eventln SFBool set_bind 
eventOut SFBool isBound 
] 

["urn:inet:blaxxun.com:node:Fog2", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Fog2"] 


Field description 


visibilityStart distance between user and fog start 

in meters 

For all other fields please see the VRML97 Spec. 

Examples 

no examples available yet. 


HUD 


Introduction 

A HeadllpDisplay is a common geometry, which is ’carried’ with the user in his 
viewing frustrum. This may be useful to design user interfaces in 3D. 

This node is equivalent to a VRML HUD construct using a Transform, Proximity 
Sensor, and Collision { collide FALSE }. 

Children are displayed relative to the viewer and not relative to the avatar posi¬ 
tion in 3rd person viewing mode. 

Node definition 

HUD { 

field SFVec3f bboxSize -1 -1 -1 
field SFVec3f bboxCenter 000 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventln MFNode removeChildren 
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For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 


EXTERNPROTO HUD[ 
field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 


[ "urn:inet:blaxxun.com:node:HUD", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#HUD"] 


Field description 


bboxSize 

bboxCenter 

children 

addChildren 

removeChildren 


Examples 

no examples available yet. 


bounding box of the HeadllpDisplay 
bbox center 

list of 3D nodes, that form the HUD 
eventln for adding nodes to the list of 
nodes 

eventln for removing nodes from the 
list of nodes 


ImageTexture 

Introduction 

Besides the common standard fields of the ImageTexture node, blaxxun Contact 

support additional fields to provide better download control. 

Node definition 

ImageTexture { 

#... standard fields 
eventOut SFBool isLoaded 
eventln SFBool set_unload 

} 


blaxxun 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 


77 





Extensions - Node Extensions 


EXTERNPROTO ImageTexture[ 
url [""] 
repeats TRUE 
repeatT TRUE 

eventOut SFBool isLoaded 
eventln SFBool set_unload 
] ["urn: inet :blaxxun. commode : ImageTexture", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#ImageTexture"] 

Field description 


isLoaded 


set unload 


Examples 

no example available yet. 


indicates loading success, TRUE is 
sent once the inline node is loaded, 
FALSE is sent if the inline nodes url 
couldn't be retrieved or there was 
another problem with the data, 
used to unload a Node from mem¬ 
ory, however the application should 
generally ONLYuse this eventln, if 
it’s sure that the node is currently not 
part of the visible node subsets (i.e. 
out of viewing frustrum, not in tra¬ 
versed scene graph etc.) 


Inclusion 


Introduction 

In order to provide better culling mechanisms for complex scenes, we proposed 
several nodes, which help optimizing the contant. The idea is, once you are in¬ 
side a room, you cannot see anything outside. Children of an Inclusion node are 
only traversed if the viewpoint is in one of the proxy objects or if proxy is NULL. 
In combination with BspTree’s if an Inclusion node becomes active, the node sig 
nals the BSP-Tree logic to stop processing. 

The current implementation allows the following nodes inside the proxy scene 
graph: Group Transform, Box, Sphere, Cylinder, IndexedFaceSet (must be con 
vex) 

Please see also “blaxxun3D specifics” on page 110, “BSPTree” on page 54, 
“BSPGroup” on page 56 and “CullGroup” on page 66 
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Node definition 

Inclusion { 

field SFVec3f bboxSize -1 -1 -1 
field SFVec3f bboxCenter 000 
exposedField SFBool enabled TRUE 
exposedField SFNode proxy NULL 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventln MFNode removeChildren 
eventOut SFBool isActive 
eventOut SFTime enterTime 
eventOut SFTime exitTime 
} 

For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Inclusion[ 

field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField SFBool enabled 
exposedField SFNode proxy 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 
eventOut SFBool isActive 
eventOut SFTime enterTime 
eventOut SFTime exitTime 


] 

["urn:inet:blaxxun.com:node:Inclusion", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Inclusion"] 


Field description 


bboxSize 

bboxCenter 

enabled 

proxy 

children 


addChildren 

removeChildren 


size of bounding box 
center of bounding box 
enabled state 

list of 3D nodes, which are only tra¬ 
versed if the viewpoint is in one of 
the proxy objects or if proxy is NULL, 
eventln for adding children nodes 
eventln for removing children nodes 
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isActive 

enterTime 


activity state 


exitTime 


eventOut that signals entering the 
inclusion area 

eventOut that signals leaving the 
inclusion area 


Examples 

no examples available yet. 


Inline2 


Introduction 

In order to have more control about the loading process of an Inline Node and 
the processed nodes, this node provides several additional fields compared with 
a common Inline Node. 

Node definition 

Inline2 { 

field SFVec3f bboxSize -1 -1 -1 
field SFVec3f bboxCenter 000 
exposedField MFString url [] 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventIn MFNode removeChildren 
eventOut SFBool isLoaded 
eventln SFBool set unload 


} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Inline2[ 

field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField MFString url 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 
eventOut SFBool isLoaded 
eventln SFBool set_unload 

] 

["urn:inet:blaxxun.com:node:Inline2", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Inline2"] 






Field description 


Extensions 



bboxSize 


bboxCenter 

url 

children 

addChildren 

removeChildren 

isLoaded 


set unload 


Examples 

no examples available yet. 


size of bbox of the loaded inline 
nodes, Should be set manually by 
the content author to provide better 
culling. 

center of bbox 

url of file to be fetched 

list of nodes of the inlined file 

eventln to add nodes to the inlined 

nodes 

eventln to remove nodes from the 
inlined nodes 

indicates loading success, TRUE is 
sent once the inline node is loaded, 
FALSE is sent if the inline nodes url 
couldn’t be retrieved or there was 
another problem with the data, 
used to unload a Node from mem¬ 
ory, however the application should 
generally ONLYuse this eventln, if 
it’s sure that the node is currently not 
part of the visible node subsets (i.e. 
out of viewing frustrum, not in tra¬ 
versed scene graph etc.) 


KeySensor 

Introduction 

The node catches all keyboard events. If certain keys are normally associated to 
the browser, they are either not processed in the scene or by the browser. Fol¬ 
lowing the W3C-DOM-proposal [14] we propose to add a eventsProcessed 
field. If there are multiple KeyboardSensors and/or StringSensors in a world, 
only one will generate events at any given time. 

Note the KeySensor is not affected by its position in the transformation hierarchy. 

Node definition 

KeySensor { 

eventln SFBool eventsProcessed 
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exposedField SFBool enabled TRUE 
eventOut SFInt32 keyPress 
eventOut SFInt32 keyRelease 
eventOut SFInt32 actionKeyPress 
eventOut SFInt32 actionKeyRelease 
eventOut SFBool shiftKey_changed 
eventOut SFBool controlKey_changed 
eventOut SFBool altKey_changed 
eventOut SFBool isActive 


} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO KeySensor[ 

eventln SFBool eventsProcessed 
exposedField SFBool enabled TRUE 
eventOut SFInt32 keyPress 
eventOut SFInt32 keyRelease 
eventOut SFInt32 actionKeyPress 
eventOut SFInt32 actionKeyRelease 
eventOut SFBool shiftKey_changed 
eventOut SFBool controlKey_changed 
eventOut SFBool altKey_changed 
eventOut SFBool isActive 
]["urn:inet:blaxxun.com:node:KeySensor", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#KeySensor"] 


Field description 

eventsProcessed If set to TRUE no default action 


keyRelease 


enabled 

keyPress 


associated with the event is excuted 
by the browser. The flag signals the 
browser that all events are pro¬ 
cessed by the node, 
enabled state of the sensor 
generated as keys which produce 
characters are pressed. The value is 
an integer, which is the UTF-8 char¬ 
acter value for the key pressed 
generated as keys which produce 
characters are released. The value 
is an integer, which is the UTF-8 
character value for the key released 






actionKeyPress 


actionKeyRelease 


shiftKey_changed 
controlKey_changed 

altKey_changed 

isActive 


Extensions 



generated when ’non-character 
keys’ are pressed. See table below 
for key codes. 

generated when ’non-character 
keys’ are released. See table below 
for key codes 

changes of Shift-Key, TRUE while 
pressed, FALSE when released 
changes of Control-Key, TRUE 
while pressed, FALSE when 
released 

changes of Alt-Key, TRUE while 
pressed, FALSE when released 
activity state 


Action-Key key codes 

Key 

Value 

Home 

1000 

End 

1001 

PageUp 

1002 

PageDown 

1003 

Up 

1004 

Down 

1005 

Left 

1006 

Right 

1007 

F1-F12 

1008-1019 

Examples 

no examples available yet. 


Layer2D 


Introduction 

Layer2D is a MPEG4 node, which is used for scene composition in terms of 2D 
scenes. The Layer2D node is a transparent rendering rectangle region on the 
screen where a 2D scene is drawn. The rectangle always faces the viewer of the 
scene. In opposition to Layer3D, this Layer node draws 2D components (without 
depth). 
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Node definition 

Layer2D{ 

eventln MFNode addChildren 
eventIn MFNode removeChildren 
exposedField MFNode children [] 

exposedField SFVec2f translation 00 # not MPEG-4 

exposedField SFVec2f size -1 -1 
exposedField SFNode background NULL 
exposedField SFNode viewport NULL 


} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Layer2D[ 

eventln MFNode addChildren 
eventln MFNode removeChildren 
exposedField MFNode children 

exposedField SFVec2f translation # not MPEG-4 
exposedField SFVec2f size 
exposedField SFNode background 
exposedField SFNode viewport 

] 

[ "urn:inet:blaxxun.com:node:Layer2D", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Layer2D", 


Field description 


addChildren 


eventln for adding children nodes to 
this Layer 


removeChildren 


eventln for removing children nodes 
from this Layer 


children 


any 3D children nodes that define a 
3D scene. 






size 


background 


viewport 

translation 


Extensions 
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Layer size in screen co-ordinates 
ranging from 0...1. 

In case of a layer at the root of the 
hierarchy, the fraction is a fraction of 
the screen rendering area. A size of 
-1 in one direction, means that the 
Layer node is not specified in size in 
that direction, and that the size is 
adjusted to the size of the parent 
layer, or the global rendering area 
dimension if the layer is at the top of 
the hierarchy. 

If a Background node is given in 
the background field a given sky- 
Color is used as the solid back¬ 
ground fill color for the Layer, other 
forms of Background rendering are 
not supported. 

If background is NULL the back¬ 
ground is transparent and the con¬ 
tent from the parent shines through. 
Viewpoint node through which this 
Layer scene is rendered 
used for positioning the children 
geometry. 

Note: This field is not compatible 
with the MPEG4 requirements. In 
order to position a Layer MPEG4 
conform, you should use 
Transform2D. 


Implementation notes 

Please read the “Implementation notes” on page 88 for the Layer3D node as 
they are similar for both nodes. 

Examles 

no examples available yet. 


Layer3D 


Introduction 

The Layer3D node is a transparent rendering rectangle region on the screen 
where a 3D scene is shown. The Layer3D is part of the layers hierarchy, and can 
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be composed in a 2D environment with depth. Layer3D nodes enable the com¬ 
position in a 2D space with depth of multiple scenes. This allows users e.g. to 
view a 3D scene from different view points in the same scene or view different 
3D scenes in the same scene. 

A common use for this is for example a rearview mirror in a car or a Userlnterface 
overlaying a 3D scene. 

Note: Layer3D is fully supported with Contact 5.0, Contact 4.4 already provided 
a partial implementation. 

Node definition 

Layer3D{ 

exposedField SFVec3f bboxSize -1 -1 -1 
exposedField SFVec3f bboxCenter 000 
eventln MFNode addChildrenLayer 
eventIn MFNode removeChildrenLayer 
exposedField MFNode childrenLayer [] 
exposedField SFVec2f translation 0 0 
exposedField SFInt32 depth 0 
exposedField SFVec2f size -1 -1 
exposedField SFNode background NULL 
exposedField SFNode viewpoint NULL 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventln MFNode removeChildren 

} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Layer3D[ 

exposedField SFVec3f bboxSize 
exposedField SFVec3f bboxCenter 
eventln MFNode addChildrenLayer 
eventln MFNode removeChildrenLayer 
exposedField MFNode childrenLayer 
exposedField SFVec2f translation 
exposedField SFInt32 depth 
exposedField SFVec2f size 
exposedField SFNode background 
exposedField SFNode viewpoint 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 
] 
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["urn:inet:blaxxun.com:node:Layer3D", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Layer3D", 
] 


Field description 


bboxSize 
bboxCenter 
addChiIdrenLayer 

removeChi1drenLayer 

chiIdrenLayer 


translation 

depth 

size 


background 


viewpoint 

children 


bbox of the layer geometry 
center of the bbox 
eventln for adding children layers to 
this layer node 

eventln for removing children layers 
to this layer node 

group of children layers.The layering 
of the 3D layers is specified by the 
translation and depth fields, 
tranlation of layer geometry 
depth of layer 

Layer size in screen co-ordinates 
ranging from 0...1. 

In case of a layer at the root of the 
hierarchy, the fraction is a fraction of 
the screen rendering area. A size of 
-1 in one direction, means that the 
Layer node is not specified in size in 
that direction, and that the size is 
adjusted to the size of the parent 
layer, or the global rendering area 
dimension if the layer is at the top of 
the hierarchy. 

If a Background node is given in 
the background field a given sky- 
Color is used as the solid back¬ 
ground fill color for the Layer, other 
forms of Background rendering are 
not supported. 

If background is NULL the back¬ 
ground is transparent and the con¬ 
tent from the parent shines through. 
Viewpoint node through which this 
Layer scene is rendered 
any 3D children nodes that define a 
3D scene. 
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addchildren specifies a list of 3D nodes that are 

added to the Layer3D’s children 
field.. 

removeChildren specifies a list of 3D nodes that are 

removed from the Layer3D’s chil¬ 
dren field. 


Implementation notes 

There is no means for switching the active layer in order to connect the built-in 
browser navigation to a certain layer.Navigation can be done by switching the 
viewpoint node in Layer3D or changing fields in the currently referenced view¬ 
point of Layer3D. 

Anchor, TouchSensor activation is supported, and follows the layers hierarchy. 
Drag Sensors are not properly supported in Layer3D. 

Layers must be ordered manually in the scene graph for correct drawing order. 
Automatic sorting by depth for childrenLayer Layer3D nodes is not supported. 
Place top level layers at the end of the top level scene graph nodes. Overlapping 
Layers in front of other Layers must be listed after the Layer in the back, either 
on the top-level scene graph or in the childrenLayer field of the parent layer. 

There is currently no way to disable a top level headlight in children layers. A 
workaround is not to place lights at the top-level scene graph, turn off headLight 
and place DirectionalLights local in the Layer3D nodes and in Subgroups. 

Examles 

Example 1: layer_test.wri 

bottom left: a layer showing an inline 

bottom right: same scene is shown with USE but from different viewpoint 
top left: another scene in a layer 

top left: right a layer referring (USE) the 3 layers from before 
Actions: click on rose wall of castle to let a layer move. 

Example 2: bar 

main : scene with navigation 

left: layer overlay with background transparent (no HUD, can be seen when 
moving near the bar) 

top : another view of the same scene (via USE) 

Actions: click on Avatar, navigate main scene 


Example 3: boxes 






Actions: none 


Extensions 



Material 


Material transparency is blended with transparent textures or transparent GIFs. 
This is not VRML97 compliant, but was a demand from content developers. See 
also the MultiTexture node for the option of blending Material color with Textures. 


Material2D 

Introduction 

MPEG4 Node. This node is not supported in the current version of blaxxun 
Contact. It is meant for future release. 

The Material2D node specifies the characteristics of a rendered 2D Shape. 
Material2D shall be used as the material field of an Appearance node in certain 
circumstances 

Node definition 

Material2D { 

exposedField SFColor emissiveColor 0.8 0.8 0.8 
exposedField SFBool filled FALSE 
exposedField SFNode lineProps NULL 
exposedField SFFloat transparency 0 

} 

For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Material2D[ 

exposedField SFColor emissiveColor 
exposedField SFBool filled 
exposedField SFNode lineProps 
exposedField SFFloat transparency 

] 

["urn:inet:blaxxun.com:node:Material2D", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Material2D", 

] 


Field description 


emissiveColor 


unlit color 


blaxxun 
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filled 


specifies whether rendered nodes 
are filled or drawn using lines. If the 
rendered node is not filled the line 
shall be drawn centered on the ren¬ 
dered node outline. 


lineProps 


contains information about line ren¬ 
dering 


transparency 


transparancy value, 0 = opac, 1 = 
transparent 


Examles 

no examples available yet. 


MenuSensor 


Introduction 

MenuSensor displays a VRML defined Menu in the Contact 3D as right click pop 
up menu. On activation of a menu entry, the corresponding choice value is sent 
as eventOut choice. A choice value of -1 indicates a menu separator. 

Node definition 

MenuSensor { 

exposedField SFBool enabled TRUE # TRUE menu enabled, FALSE 
disabled 

exposedField SFString title "" # title for submenu entry 
exposedField MFInt32 choices [] # list of numbers 
exposedField MFString descriptions [] # description for each 
menu entry 

exposedField SFString position "" # "TOP" menu appears at the 
top of the Contact 3D menu 
eventOut SFBool isActive 

eventOut SFInt32 choice # associated choices number for user 
selected menu entry 


} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO MenuSensor[ 
exposedField SFBool enabled 
exposedField SFString title 
exposedField MFInt32 choices 
exposedField MFString descriptions 
exposedField SFString position 
eventOut SFBool isActive 






eventOut SFInt32 choice 
] 


Extensions 


[ "urn:inet:blaxxun.com:node:MenuSensor", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#MenuSensor", 
] 


Field description 

enabled 

title 

choices 

descriptions 

position 


isActive 

choice 


enable/disable the Menu 
menu title 
menu item aliases 
list menu items 

string that indicates relative position 
to Contact’s menu 

"TOP" menu appears at the top of 
the Contact 3D menu 
activity state 

evntOut that indicates the selected 
choice 


Examples 

Example : menutest .wrl 


MouseSensor 

Introduction 

Analogous to the Keyboard Sensor we define a MouseSensor that reports the 
events of the mouse. 

Node definition 

MouseSensor { 


eventIn 

SFBool 

eventsProcessed 

exposedField 

SFBool 

enabled TRUE 

eventOut 

SFVec2f 

client 

eventOut 

SFVec2f 

position 

eventOut 

SFBool 

lButton 

eventOut 

SFBool 

mButton 

eventOut 

SFBool 

rButton 

eventOut 

SFFLoat 

mouseWheel 

eventOut 

SFBool 

isActive 


} 


blaxxun 
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For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO MouseSensor[ 


eventIn 

SFBool 

eventsProcessed 

exposedField 

SFBool 

enabled 

eventOut 

SFVec2f 

client 

eventOut 

SFVec2f 

position 

eventOut 

SFBool 

lButton 

eventOut 

SFBool 

mButton 

eventOut 

SFBool 

rButton 

eventOut 

SFFLoat 

mouseWheel 

eventOut 

SFBool 

isActive 


] 

["urn:inet:blaxxun.com:node:MouseSensor", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#MouseSensor", 


Field description 


eventsProcessed 


enabled 

client 


position 

lButton 

mButton 

rButton 

mouseWheel 


If the eventsProcessed is set to 
true, no default action associated 
with the event is excuted by the 
browser. The flag signals the 
browser that all events are pro¬ 
cessed by the node, 
enabled state of the sensor 
indicates the coordinate at which the 
event occurred relative to the brows¬ 
ers client window. 

indicates the normalized coordinate 
at which the event occurred, 
generated when the left button is 
pressed and released, 
generated when the middle button is 
pressed and released, 
generated when the right buttons is 
pressed and released, 
indicates the distance rotated. If the 
wheel is rotated forward the values 
are positive, otherwise negative. 

The size of the value depends on the 
resolution of the mouse-wheel. Typ¬ 
ical values are mutiples of 120. 
reports the activity state 
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isActive 
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Examles 

please see “Generic Input Handling” on page 202 for details. 


Example: Mouse/Keyboard Input 


MovieTexture2 

Introduction 

Besides the common standard fields of the MovieTexture node, blaxxun Contact 
support additional fields to provide better media control. 

Node definition 

MovieTexture2{ 

#...standard fields 
eventln SFBool set_pause 
eventOut SFTime mediaTime 
eventOut SFVec2f imageSize 

} 

For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO MovieTexture2[ 
exposedField SFBool loop 
exposedField SFFloat speed 
exposedField SFTime startTime 
exposedField SFTime stopTime 
exposedField MFString url 
field SFBool repeats 
field SFBool repeatT 
eventOut SFTime duration_changed 
eventOut SFBool isActive 
#extra 

eventln SFBool set_pause 
eventOut SFTime mediaTime 
eventOut SFVec2f imageSize 

] 

["urn:inet:blaxxun.com:node:MovieTexture2", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#MovieTexture2", 

] 


Field description 

set_pause 

mediaTime 



pauses current media play 
reports the current media play time 
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imagesize reports the current media video 

image size 

Examples 

please see “Integrated Media” on page 25 

MultiTexture 

Introduction 

MultiTexture enables multi-texturing: a 3D object is textured with a texture com 
posed from several individual textures. Use it as a value for the texture field in 
an Appearance node. 

Node definition 

MultiTexture{ 

exposedField SFBool materialColor FALSE 
exposedField SFBool materialAlpha FALSE 
exposedField SFBool transparent FALSE 
exposedField SFBool nomipmap FALSE 
exposedField MFString mode [] 
exposedField MFString type [] 
exposedField MFNode texture [] 
exposedField MFNode textureTransform [] 
exposedField MFInt32 textureOp [] 
exposedField SFColor color 111 
exposedField SFFloat alpha 1 

} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO MultiTexture{ 

exposedField SFBool materialColor 
exposedField SFBool materialAlpha 
exposedField SFBool transparent 
exposedField SFBool nomipmap 
exposedField MFString mode 
exposedField MFString type 
exposedField MFNode texture 
exposedField MFNode textureTransform 
exposedField MFInt32 textureOp 
exposedField SFColor color 
exposedField SFFloat alpha 


] 





Extensions 

["urn: inet :blaxxun. commode :MultiTexture", 


"http://www.blaxxun.com/vrml/protos/nodes.wrl#MultiTexture 


Field description 


materialColor 

If materialColor is TRUE, RGB tex¬ 
tures are modulated with the Mate¬ 
rial diffusecolor or with the object 
vertexcolor (if present). Use it to 
modulate RGB RGBA textures with 
the color resulting from the Material 
or the primitive Vertex colors. 

materialAlpha 

If materialAlpha is TRUE, alpha tex¬ 
tures are modulated with the Mate¬ 
rial transparency alpha value. 

transparent 

If TRUE MultiTexture results in an 
image with alpha and should be 
drawn later 

nomipmap 

if TRUE turn of mip-mappiing for this 
texture 

mode 

controls the type of blending opera¬ 
tion. The VRML97 available modes 
correspond to MODULATE for a lit 
Appearance, and REPLACE for an 
unlit Appearance. 

type 

texture 

please see “Multitexturing” on page 
210 for all available blending modes 

contains a list of Texture nodes, e.g. 
ImageTexture, PixelTexture, Movi- 
eTexture, CompositeTexture3D. 

textureTransform 


textureOp 

color 

alpha 



Examples 

please see “Multitexturing” on page 210 
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MultiTextu reCoordinate 

Introduction 

MultiTextureCoordinate is used in combination with “MultiTexture” on page 94. 
This node is used to hold the texture co-ordinates for the several textures. 

For a MultiTexture node with an IndexedFaceSet without a MultiTextureCoordi¬ 
nate texCoord node, texture coordinates for channel 0 are replicated along the 
other channels. Likewise if there are too few entries in the texCoord field, the last 
entry is replicated. 

Please see also the node description for “MultiTexture” on page 94, and the 
chapter “Multitexturing” on page 210 

Node definition 


MultiTextureCoordinate{ 

exposedField MFNode coord [] 

} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO MultiTextureCoordinate{ 
exposedField MFNode coord 

] 

["urn:inet:blaxxun.com:node:MultiTextureCoordinate", 

"http://www.blaxxun.com/vrml/protos/ 
nodes.wrl#MultiTextureCoordinate", 

] 

Field description 

coord list of TextureCoordinate nodes, 

each one for the appropriate texture 


Examples 

please see “Multitexturing” on page 210 


Nurbs 


(R) 

As part of our development efforts for Pentium III support, we have imple¬ 
mented NURBS technology in blaxxun Contact 4.1. With NURBS complex 3D 






Extensions 



curves are represented with a minimum of data, allowing a new level of visual 
display and animation quality for Internet delivered 3D graphics. 


To learn about blaxxuns NURBS development, including NURBS-related set¬ 
tings in blaxxun Contact, sample content, project results and our proposed 
NURBS extension for VRML97, see “NURBS Proposal” on page 197 


Trimmed NURBS extension nodes : 

• Contour 

• Polyline2D 

• NurbsCurve2D 

• TrimmedSurface 


A conversion utility from Openlnventor NURBS format to VRML is also available 
from the above mentioned NURBS project page. 

Trimmed NURBS support is not available in Contact 5.0. 

The Nurbs extension is a VRML 97 amendment. 


Occlusion 

Introduction 

In order to provide better culling mechanisms, especially for complex scenes, 
which consist of indoor and outdoor parts, we proposed several nodes. 

Occlusion is a group node with an additional proxy geometry triggering an inside/ 
outside processing. Children are meant to contain the inside view of the room, 
proxy is supposed to contain the bounding shape for the room, i.e. a Box {} node. 

During traversal the current viewpoint is compared with all geometry nodes in the 
proxy subgraph. If the viewpoint is outside all geometry nodes, children will be 
not visited for display. If the viewpoint is inside the proxy the children will be vis¬ 
ible. 

Whenever children become visible or invisible isActive, enterTime and exitTime 
events are generated similar to the ProximitySensor. Occlusion's behaviour can 
be switched to the normal Group behaviour by setting enabled to FALSE. This is 
designed for cases where temporarily the room becomes visible from the out¬ 
side, for example if a door or window has been opened, to look inside the room. 


blaxxun 


Please see also “Inclusion” on page 78, “BSPTree” on page 54, “BSPGroup” on 
page 56 and “CullGroup” on page 66 
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Node definition 

Occlusion { 

field SFVec3f bboxSize -1 -1 -1 
field SFVec3f bboxCenter 000 
exposedField SFBool enabled TRUE 
exposedField SFNode proxy NULL 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventIn MFNode removeChildren 
eventOut SFBool isActive 
eventOut SFTime enterTime 
eventOut SFTime exitTime 


} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Occlusion[ 

field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField SFBool enabled 
exposedField SFNode proxy 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 
eventOut SFBool isActive 
eventOut SFTime enterTime 
eventOut SFTime exitTime 

] 

[ "urn:inet:blaxxun.com:node:Occlusion", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Occlusion", 


Field description 
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bboxSize 


bboxCenter 


proxy 


enabled 


addChildren 

removeChildren 


children 


bounding box 
center of bounding box 
enabled state 

geometry, which is used to check, 
whether the user is inside the speci¬ 
fied area 

list of 3D nodes, which are visible in 
dependance of the proxy check 
eventln for adding children nodes 
eventln for removing children nodes 






isActive 

enterTime 

exitTime 


Examples 

no examples available yet. 
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TRUE if user is inside the proxy 
defined area, FALSE if not 
eventOut, when user enters proxy 
area 

eventOut, when user leaves proxy 
area 


Particle Systems 

Introduction 

The Particles Node creates a dynamic generated Particle System. Particles is a 
geometry node. Particles are rendered per default as a textured billboarded 
quad. They are emitted from a sphere centered at emitterPosition. Each particle 
internally stores the properties position, velocity, radius, RGBA color, lifeTime. A 
particle is destroyed once the radius reaches 0, the alpha values reaches 0 or 
the lifeTime expires. Another special ending condition is if the particle reaches 
the y=0 plane. In this case if numSparks is >0 secondary particles are created. 

Several variables can be randomized using the corresponding variation 
parameter, variation o means no variation, values above 0 to 1 an random¬ 
ize value according to 

parameter *(1.0 - (Math.random() * variation)) 

Particles are not selectable or collidable. 


Node definition 


Particles{ 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 


SFVec3f bboxSize -1 -1 -1 
SFVec3f bboxCenter 000 
SFFloat lodRange 100 
SFBool enabled TRUE 
SFFloat particleRadius 0.1 
SFFloat particleRadiusVariation 0 
SFFloat particleRadiusRateO 
SFNode geometry NULL 
SFVec3f emitterPosition 030 
SFFloat emitterRadius 0 
SFFloat emitterSpread 0.25 
SFVec3f emitVelocity 2.5 5 2.5 
SFFloat emitVelocityVariation 0.5 
SFRotation emitterOrientation 0 1 
SFFloat creationRate 500 


0 


0 


blaxxun 
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exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 

exposedField 


SFFloat creationRateVariation 0 
SFInt32 maxParticles 500 
SFTime maxLifeTime5 
SFFloat maxLifeTimeVariation 0 
SFVec3f gravity 0 -9.8 0 
SFVec3f acceleration 000 
SFColor emitColor 111 
SFFloat emitColorVariation 0 # 5.0 


exposedField SFColor fadeColor 0.25 0.25 0.25 
exposedField SFFloat fadeAlpha 1.0 
exposedField SFFloat fadeRate 0.25 
exposedField SFInt32 numTrails 0 
exposedField SFInt32 numSparks 0 
exposedField SFVec3f sparkGravity 0-50 
exposedField SFColor sparkFadeColor 000 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 


EXTERNPROTO Part 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 
exposedField 


icles{ 

SFVec3f bboxSize 

SFVec3f bboxCenter 

SFFloat lodRange 

SFBool enabled 

SFFloat particleRadius 

SFFloat particleRadiusVariation 

SFFloat particleRadiusRate 

SFNode geometry 

SFVec3f emitterPosition 

SFFloat emitterRadius 

SFFloat emitterSpread 

SFVec3f emitVelocity 

SFFloat emitVelocityVariation 

SFRotation emitterOrientation 

SFFloat creationRate 

SFFloat creationRateVariation 

SFInt32 maxParticles 

SFTime maxLifeTime 

SFFloat maxLifeTimeVariation 

SFVec3f gravity 

SFVec3f acceleration 

SFColor emitColor 

SFFloat emitColorVariation 

SFColor fadeColor 

SFFloat fadeAlpha 

SFFloat fadeRate 

SFInt32 numTrails 
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exposedField SFInt32 numSparks 
exposedField SFVec3f sparkGravity 
exposedField SFColor sparkFadeColor 

] 

["urn:inet:blaxxun.com:node:Particles", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Particles", 


Field description 

bboxSize 

bboxCenter 

lodRange 

enabled 

particleRadius 

particleRadiusVariation 

particleRadiusRate 

geometry 

emitterPosition 

emitterRadius 

emitterSpread 

emitVelocity 


size of the bounding box of the 
whole particle system. May be set 
for culling purposes, 
center of the bbox 
gradually scales the creationRate to 
0 if the viewer moves more than 
specified away from the emitterPosi¬ 
tion. lodRange 0 turns off the LOD 
effect. 

If a Particles node is disabled, cre¬ 
ation of new particles is stopped, but 
current particles are simulated until 
their end. 

radius of a single particle 

radius may vary about the specified 

value 

geometry node which is used a the 
particle geometry, the node is trans¬ 
lated according to the particle posi¬ 
tion and scaled according to particle 
radius. Particle color is ignored in 
this mode. 

Particles are emitted from a sphere 
centered at emitterPosition 
radius of the emitting sphere, if 
radius is 0 the emitter is a single 
point. 

emitterSpread is a cone with angle 
0..1. If the spread is 1.0, particles are 
emitted over the whole sphere 
velocity value the particles are emit¬ 
ted with 

variation of the emitVelocity 


emitVelocityVariation 
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emitterOrientation 

direction of the cone the particles 
are emitted from 

creationRate 

number of particles that are created 
per second 

creationRateVariation 

maxParticles 

maxLifeTime 

maxLifeTimeVariation 

gravity 

variation value of creation rate 

maximum number of particles 
maximum life time of a particle 

variation value of the life time 

global vector that effects particles 
after emission 

acceleration 

global vector that effects particles 
after emission 

emitColor 

color of particle at emission time. 

The initial RGBA color (emitColor, 

Alpha 1.0) is interpolated to fade- 
Color, fadeAlpha over the lifetime of 
the particle. 

emitColorVariation 

fadeColor 

variation value of emitColor 

color value to which the emitted par¬ 
ticle fades to 

fadeAlpha 

alpha value, the particle is faded to 
over the lifetime 

fadeRate 

numTrails 

in the Billboard drawing case, parti¬ 
cles can leave a trail using 
numTrails (0..10) 

numSparks 

number of secondary particles, that 
are created when the particle 
reaches the y=0 plane. 

sparkGravity 

gravity value for the created second¬ 
ary particles 

sparkFadeColor 

color value the spark fades to 


Implementation notes 

The Contact 4.4 DX render pipeline does not render the particles with their cur 
rent alpha value. Alpha is supported with Contact 5 Dirext 7 and OpenGL Driv¬ 
ers. 

Examples 
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Test 1 
Fire test 

with mirror effect 






• using the geometry field 

• Moving emitter 

• simple Particle Editor 

• Flashy trails 

• some fire 

• some fx 


Extensions 



Portal 


Introduction 

Cells & Portals allows the visibility management of complex indoor environ¬ 
ments.For further details, please also read the documentation at "Ceiis&Por- 
tals" on page 234 

The Cells and Portals technique combines several extension nodes. Please see 
also the node definitions for “Cell” on page 60 and “CellGroup” on page 62 


Node definition 


Portal { 

exposedField 

exposedField 

exposedField 

exposedField 

} 


SFBool enabled TRUE 
SFBool CCW TRUE 
SFNode coord NULL 
SFNode cell NULL 


Field description 


enabled controls portal processing. 

If enabled is TRUE processing the 
Portal is active and will check for vis¬ 
ibility, if enabled is FALSE the Porta- 
lis not active and is treated invisible, 
ccw specifies the handedness of the 

polygon, see IndexedFaceSet ccw 
field for explanation. 

coord specifies a Coordinate node contain¬ 

ing the 3D Polygon of the Portal 

cell the cell which is seen through the 

Portal 
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Examples 

8*8 script generated in-door scene 

16*16 script generated out-door scene (with visibilityLimit) 

The culling rate can be observed using the F8 keys, the last number represents 
the number of primitives (IndexedFaceSet’s) after all culling. (ViewFrustrum,Cell 
& Portal culling.) 

Please see also the chapter “Cells&Portals” on page 234 


Positionlnterpolator2D 

Introduction 

MPEG4 Node. This node is not supported in the current version of blaxxun 
Contact. It is meant for future release. 

This node fills the lack of the missing 2D Interpolators in the VRML97 Spec. The 
node works like a common Positionlnterpolator with the difference of the keyVal- 
ues being multiple SFVec2f values. 

A common use for this node is for example texture animation. In this case this 
Interpolator would drive a TextureTransform node. 

Node definition 


PositionInterpolator2D { 

eventln SFFloat set_fraction 
exposedField MFFloat key [] 
exposedField MFVec2f keyValue [] 
eventOut SFVec2f value_changed 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO PositionInterpolator2D{ 
eventln SFFloat set_fraction 
exposedField MFFloat key 
exposedField MFVec2f keyValue 
eventOut SFVec2f value_changed 

] 

["urn:inet:blaxxun.com:node:PositionInterpolator2D", 

"http://www.blaxxun.com/vrml/protos/ 
nodes.wrl#PositionInterpolator2D ", 

] 
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Field description 

usage and means of the fields like in common interpolators. Please see VRML97 
Spec for details 


Examples 

no examples available yet. 


Rectangle 

Introduction 

MPEG4 Node. This node is not supported in the current version of blaxxun 
Contact. It is meant for future release. 

This node specifies a rectangle centered at (0,0) in the local coordinate system. 
The size field specifies the horizontal and vertical size of the rendered rectangle. 

Node definition 

Rectangle { 

exposedField SFVec2f size 2 2 

} 

For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Rectangle[ 

exposedField SFVec2f size 


["urn:inet:blaxxun.com:node:Rectangle", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Rectangle", 
] 


Field description 


size 


size of the rectangular shape 


Examples 

no examples available yet. 


Script 


blaxxun 


Extensions regarding the Script node are discussed in detail in chapter “Scripting 
extensions” on page 32 
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Selection 


Introduction 

Similar to a Collision node this node allows to define an invisible mouse selection 
proxy (e.g. large Rectangle for Text, bigger box for a fine detailed geometry) or 
to turn off selection completely (e.g. in order to pick through transparent shapes). 

Node definition 

Selection { 

field SFVec3f bboxSize -1 -1 -1 
field SFVec3f bboxCenter 000 

exposedField SFBool collide TRUE # as in Collision node 
exposedField SFBool select TRUE # if false, children are not 
existing for Anchor / dragsensor selection 

exposedField SFNode proxy NULL # proxy used for selection 
processing as well 

exposedField MFNode children [] 
eventln MFNode addChildren 
eventIn MFNode removeChildren 


} 


For Compatibility with other VRML97 Browsers you should implement the node 
as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Selection[ 

field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField SFBool collide 
exposedField SFBool select 
exposedField SFNode proxy 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 

] 

["urn:inet:blaxxun.com:node:Selection", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Selection", 


Field description 


bboxCenter 

collide 


bboxSize 


bounding box size 
center of bounding box 
if False, not collision detection is 
performed for the children of this 
node 
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if FALSE, children are not selectable 
geometry to perform select sensing 
(not renderred) 
list od 3D nodes 
eventln to add children 
eventln to remove children 

Examples 

no examples available yet. 


select 

proxy 

children 

addChildren 

removeChildren 


Text/FontStyle 

Introduction 

A common problem with Text nodes in VRML is the high amount of produced tri¬ 
angles because of the necessary tesselation. With Contact 4.3 and higher there 
is an option to create a textured rectangle for each character. The user supplies 
a special Font texture in a imageTexture node and sets the fontstyle family at¬ 
tribute to "TEXTURE". 

Shape { 

appearance Appearance { 
texture DEF FONTT ImageTexture { 
url "font512tr.gif" 
repeats FALSE repeatT FALSE 
} 

material Material { 
diffuseColor 111 
} 

} 

geometry Text { 

string [ "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ] 
fontstyle Fontstyle { 
family ["TEXTURE"] 
justify "LEFT" 

} } } 

Field description 

The Text attributes length and maxExtent, the Fontstyle attributes size, 
spacing, leftToRight, topToBottom, justify and style = PLAIN 
or italic are implemented for TEXTURE text. The square texture map is divid¬ 
ed into 16*16 cells for 256 different characters, the character 0 starts in the upper 
left corner of the pixel image. The character width is scaled by 0.8. The Appear¬ 
ance node or Texture node should be reused between different text strings for 
speed. For special effects or fonts the texture map may be tuned. Using textures 
with alpha (or a transparent GIF) gives a transparent background. Using gray- 
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scale or black & white textures allows color changes using the Material diffuse- 
Color. 

To further optimize the Text texture resolution and layout, custom layout settings 
can be specified with up to 7 numbers after the family "TEXTURE" string. The 
format is "TEXTURE minChar maxChar cols rows aspect extraSpace shift" 


minChar 

minimal character code - default 0 

maxChar 

maximal character code - default 
255 

cols 

number of characters per texture 
horizontal -16 

rows 

number of character rows vertical - 
16 

aspect 

float, default 0.8 - width scaling fac¬ 
tor 

extraSpace 

float, default 0.0 extra spacing 
between characters 

shift 

float default 0, italic shift factor for 
top of character box 


If an application only needs a certain continous range of characters, the texture 
can be optimized for higher resolution characters (or sprites). 

Changes to polygonal Text 

The standard polygonal Text was changed in the following way: The default res¬ 
olution for text size 1.0 was reduced. Text size 0.1 produces a coarse Font con¬ 
tour approximation, 10.0 a higher approximation. 

The FontStyle style attribute "OUTLINE" produces only fast lineset outline char¬ 
acters. This option can only be enabled for Contact 4.3 and higher and might 
cause exceptions in Versions prior to 4.3. 

The FontStyle style attribute "EXTRUDE" produces extruded 3D Text with a 
depth of 1.0. Please beware of the high triangle count possibly produced, (e.g. 
use the size 0.1 option for coarser outline tesselation.) 

It is also possible to provide a Windows True Type font name in the family set¬ 
ting. 

In Contact 4.4 the following Windows specific language codes are recognized : 

ANSI, DEFAULT, SYMBOL, SHIFTJIS, HANGEUL, HANGUL, GB2312, 
CHINESEBIG, OEM, JOHAB, HEBREW, ARABIC, GREEK, TURKISH, 
VIETNAMESE, THAI, EASTEUROPE, RUSSIAN, MAC, BALTIC 






Extensions 



The FontStyle attribute "WEiGHT#number" allows to fine tune the font weight, 
typical values are 0.. 1000 where bold is 700. 


Examples 

• TextureText with the font texture font512.gif 

• TextureText with embossed font texture font512emb.gif 

• Hebrew example 

• Symbol example 


Transform2D 

Introduction 

MPEG4 node. 

The Transform2D node allows the translation, rotation and scaling of its 2D chil¬ 
dren objects. 

Node definition 

Transform2D { 

eventln MFNode addChildren 
eventln MFNode removeChildren 
exposedField MFNode children [] 
exposedField SFVec2f center 0 0 
exposedField SFFloat rotationAngle 0 
exposedField SFVec2f scale 1 1 
exposedField SFFloat scaleOrientation 0 
exposedField SFVec2f translation 0 0 

} 

For Compatibility with other VRML97 Browsers you should implement the node 

as an EXTERNPROTO using the following syntax. 

EXTERNPROTO Transform2D{ 

eventln MFNode addChildren 
eventln MFNode removeChildren 
exposedField MFNode children 
exposedField SFVec2f center 
exposedField SFFloat rotationAngle 
exposedField SFVec2f scale 
exposedField SFFloat scaleOrientation 
exposedField SFVec2f translation 

] 


blaxxun 


[ "urn:inet:blaxxun.com:node:Transform2D", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#Transform2D", 
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Field description 


addChildren 


center 


removeChildren 


children 

rotationAngle 


scale 

scaleOrientation 

translation 


eventln for adding children nodes to 
this Transform 

eventln for removing children nodes 
from this Transform 
list of 3D nodes 

rotation angle in radians about the 

point specified by center 

scale factor 

scale orientation 

translation value 

center 


Implementation notes 

By now this node is only partly supported. Nevertheless, when using Layer2D/ 
Layer3D nodes it is recommended to use this node to position the layer instead 
of the translation field of the layer, since the translation field will possibly not be 
supported by MPEG-4 and may therefor underlay changes in future releases. 

Examples 

no examples available. 


blaxxun3D specifics 


The blaxxun3D Java Applet is blaxxun’s core implementation of the Core X3D 
Specification. Itis composed of a very lightweight set of 3D scene elements and 
programming interfaces upon which a wide variety of 3D applications can be 
built. It is a strict subset of the VRML 97 specification and it is based on these 
concepts. 

Because of this, the above mentioned VRML Extensions are not available in 
blaxxun3D. 
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Embedding blaxxun Contact 

General 

Because blaxxun Contact serves as a Browser Plug-In, it is embedded into html 
using the following tag: 

cOBJECT CLASSID="CLSID:4B6E3013-6E45-11D0-9309-0020AFE05CC8" 
ID=Contact3D WIDTH=100% HEIGHT=85%> 

<PARAM NAME="SRC" VALUE="yourVrmlFile.wrl"> 

<EMBED NAME="Contact3D" SRC="yourVrmlFile.wrl" 

TYPE="application/x-cc3d" WIDTH=100% HEIGHT=85%> 

</EMBED> 

</OBJECT> 

Please notice that a different tag is necessary for Netscape (’embed’) and Inter- 
netExplorer (’object’) and that booth tags need to be nested together. The value 
for CLASSID is the same for any implementations of blaxxun Contact worlds. 

The embedded object can now be accessed by its name (for InternetExplorer ID) 
Contact3D through JavaScript. Please see “JavaScript-EAl” on page 153 for 
details. 

Additional Parameters 

There are several additional parameters available, that help you configure the 
plugin. 


VRML-DASHBOARD 0|FALSE 

FULLSCREEN-MODE 

1024x768x16 

TIMER-INTERVAL ulong number 
AVATAR-URL avatarUrl 


AVATAR-DISPLAY 1|FALSE 


turns off the navigation panel for 
Contact 4.41 or lower. Not neces¬ 
sary for Contact 5 or higher, 
sets a fullscreen mode preference , 
built-in default is 640x480x16 
Timer interval in milliseconds 
Url for 3rd person mode avatar, 
default is avatar.wri in the blaxxun 
Contact install directory or the 
selected avatar of the community, 
turns on/off the 3rd person viewing 
mode 
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<EMBED SRC="test.wrl" 
HEIGHT=3 00 WIDTH=400 
noJavax/EMBED> 


In Netscape browsers startup of the 
plugin if the EAI is not used can be 
accelerated with the nojava option 



The following options are only valid for InternetExplorer (Additional object tag 
parameters) 


FORCE-HW TRUE 

FORCE-RGB TRUE 


HW-PROBLEM-CHECK FALSE 

HIDE-CURSOR TRUE 

FAST-MODE TRUE 

SPLASH-SCREEN url 
STARTUP-SCREEN FALSE 

FULLSCREEN-mode modestring 


uses the Hardware Direct3D Driver if 
present. There is an automatic fall¬ 
back to software driver if there are 
no or only limited hardware 
resources. 

In case the current driver preference 
does not support RGB lighting (e.g. 
the default "High Speed" setting), an 
Direct3D RGB mode capable driver 
is selected. 

The option is recommended if the 
world-author requires best shading 
& texture quality with the drawbrack 
off slower rendering performance if 
no 3D hardware is present. 

This option disables the hardware 
problem popup dialog box. This 
option is recommended if several 
CC3D instances are on one HTML 
page. 

hides Contact3ds cursor. Useful for 
applications providing their own 
feedback e.g. in fullscreen mode, 
turns on full cpu usage mode. Useful 
for benchmark applications, 
an url for the startup screen 
Contact4.41 or higher suppresses 
the blaxxun interactive start up 
world. Use with a source VRML file 
of your choice to provide a commu¬ 
nity specific start up screen 
the fullscreen display mode 
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Embedding blaxxun3D 

General 

Embedding blaxxun3D on an HTML page requires minimally the following lines 
of HTML code: 


<applet archive="blaxxun3d.jar" code="com/blaxxun/bx3d/ 
blaxxun3d.class" name="blaxxun3d" width="320" height="240"> 
<param name=scene value="content.wrl"> 

Sorry, your browser doesn't support Java. 

</applet> 

In this case the files blaxxun.jar and content.wri need to be placed in the direc¬ 
tory in which the HTML page resides. The width and height attributes determine 
the size of 3D rendering area. Browsers that support Java (most if not all) auto¬ 
matically download the viewer code in blaxxun3d.jar; the applet then downloads 
the VRML content. 

Please note that earlier versions of blaxxun3D (v < 2.2) used a different package 
structure. In this case you need to refer to the renderer with the following line 
instead the one mentioned above: 

code="blaxxun/blaxxun3d.class" 

I case that you want to connect to the browser applet via Java or Javascript you 
need to specify a name in the name attribute and additionally you have to set the 
mayscript attribute, in order to allow the browser applet to receive external calls. 

Applet-Parameters 

Adding the following applet parameters can customize the operation of 
blaxxun3D. 


Scene 
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<param name=scene relative URL or URL of the scene to 

value= "vrml/content. wrl " > load. 



Besides loading regular vrml files 
blaxxun3D offers the possibility of 
loading bx3D archives. These 
archives have the suffix M .bx3d M and 
contain all vrml files of the scene as 
well as all used textures. They can 
be created by using the bx3d wizard. 
Packing all used media files enables 
blaxxun3D to download and initialize 
a 3D scene much faster than loading 
/ initializing regular vrml files. 


Loading 

<param name=loading 
value="static"> 

“static” loads everything before 
showing the scene 

“dynamic” when setting the loading 
flag to dynamic, blaxxun3d will dis¬ 
play the scene immediately. The tex¬ 
tures will be added subsequently to 
the scene after being loaded. By 
using this flag the user will see an 
(“uncompletely loaded”) world much 
earlier than in static mode. 


See the blaxxun3D Wizard docu¬ 
mentation for more info about how to 
create a bx3D archive. 

defines the way, how blaxxun3D 
behaves at loading time: 


Version 

<param name=version 
value="on"> 


Statistics 


default: static 

if set to “on”, blaxxun3D shows the 
version number while loading 

default: off 
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<param name=statistics 
value="off"> 


Lighting 

<param name=lighting 
value="on"> 


Antialiasing 


Integrating 3D in HTML 


blaxxun 


if set to “on” blaxxun3D shows statis¬ 
tics while playing a scene. This also 
enables the VRML diagnostic output 
to the Java console. Statistics 
shown: 

*fps (frame per seconds) 

*pnts (points calculated per frame) 

*faces (faces drawn per frame) 

*norms (normals calculated per 
frame) 

*frm (number of total frames drawn) 
default: off 

switch illumination on or off. If set to 
“off” all lights in the scene are dis¬ 
abled. The scene will only appear 
illuminated with a full ambient light. 
This mode has the best rendering 
performance results. 

default: on 
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<param name=antialiasing defines how often the Tenderer per- 
value=" oneshot " > forms the antialiasing filter. Possible 

options: 

“on” - enable true per pixel antialias¬ 
ing on every rendered frame. Note 
this will significantly reduce render¬ 
ing speed. 

“off - disable antialiasing 

“oneshot” - the Tenderer performs 
the antialiasing filter on a static 
frame. This means that whenever 
the renderer has no continuously job 
to proceed (e.g. rendering of an ani¬ 
mation) it will do a one time antialias¬ 
ing of the current frame, (recom¬ 
mended) 

default: oneshot 

bilinear filtering optimizes the ren¬ 
dered texture quality. Possible 
options: 

“on” - enable bilinear filtering on 
every rendered frame. Note this will 
significantly reeduce rendering 
speed. 

“off” - disable bilinear filtering 

“oneshot” - the renderer performs 
the bilinear filtering on a static frame. 
This means that whenever the ren¬ 
derer has no continuously job to do 
(e.g. rendering of an animation) it 
will do a one time bilinear filtering of 
the current frame, (recommended 
setting) 


Bilinear Filtering 

<param name=bilinear 
value="oneshot"> 


Textcolor 


default: oneshot 
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<param name=textcolor 
value="ffffff"> 

color for the text and for the loading 
bar (rrggbb in hex) 

Shadowcolor 

<param name=shadowcolor 
value=" 808080"> 

default: ffffff 

color of the shadow of the text and 
the back of the loading bar 

Backcolor 

<param name=backcolor 
value=" 202020 "> 

default: 808080 

background color while loading 
(useful to set the initial background 
color of the applet the same as the 

HTML page.) 

Backimage 

<param name=backimage 
value= 

"image/background.jpg" > 

default: 505050 

progressive background image 
while loading This parameter is use¬ 
ful to set the initial background 
image of the applet. This picture is 
show while downloading the VRML 
content. 

Showanchor 

<param name=showanchor 
value="on" > 

default: none 

if set to “on”, the anchor descriptions 
are shown as tooltips 

Anchortextcolor 

<param name=anchortext- 
color value= " Oxff 0000"> 

Anchorbackcolor 

<param name=anchorback- 
color value= " Oxff 0000"> 

ForceGC 

<param name=forceGC 
value=" 10000"> 

default: off 

anchor tooltip text color 

anchor tooltip background color 

forces a garbage collector call every 
n frames. Workaround to make 
shure that there is a memory clean 
up even at browsers with weak gar¬ 
bage collector implementation. 


Default is 10000 
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blaxxun3D - Applet Extensions 

Using the powerful API it is possible to extend the core functionality of 
blaxxun3D. Due there is no support for navigation in the core X3D profile we pro¬ 
vide two extensions for certain navigation modes. Each of these extensions is an 
own applet, which connects to the browser applet and controls the 3D scene. 

Using this technique you may also write your own extensions. In this case please 
see also “API” on page 153 

Walk Extension 

This example extends blaxxun3D's core functionality towards a simple walk nav¬ 
igation. It implements three ways of navigation. The user is either able to click 
into the applet and drag the mouse to the desired direction. The same effect can 
be achieved with pressing the cursor keys while the applet has the focus, (click 
into the applet to give the applet the focus). Another option is to provide HTML- 
Buttons and trigger the appropriate action via Javascript as long as the button is 
pressed or the mouse is over it. 

To achieve a most intuitive navigation the world's author should design his world 
in the xz-pane or parallel to it. 

The following parameters configure the walk applet. 


collision 


turns collision detection on or off 


mindistance 


extends 


default: on 

an extra offset specifiing the mini¬ 
mum distance between viewer and 
world's objects 

default: 0.5 

name of the render applet, this navi¬ 
gation applet is supposed to connect 
to. 

default: “browser” 


The walk speed is defined in the VRML node Navigationlnfo. 

Press shift key while dragging to speed up movement. 

blaxxun provides this extension class inside the free blaxxun3D development 
kit. 
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Examine Extension 

This Applet extends blaxxun3D’s functionality towards an examine modus. The 
user is able to rotate the displayed object simply with dragging the mouse into 
the desired direction. He can also zoom in and out by holding down the ctrl-key 
and dragging the mouse back and forth. The cursor keys can also be used to ro¬ 
tate/zoom the object. The examine mode assumes the object to rotate is called 
ROOT within the VRML file. If blaxxun3D can’t find this node, it will treat the first 
found Transform node as node to be examined. 

Applet’s parameters: 


turnspeed 

controls the rotation speed in m/s 

zoomspeed 

default: 1 

controls the zooming speed in m/s 

minDistance 

default: 1 

contains the minimum distance 
between viewer and object (makes 
shure the user won’t collide with the 
object) 

maxDistance 

default: 4 

contains the maximum distance 
between viewer and object 

twistmode 

default: 10 

If set to “on”, model rotates only 
around object's y axis 

extends 

default:”off” 

name of the render applet, this navi¬ 
gation applet is supposed to connect 
to. 

default: “browser” 


blaxxun provides this extension class inside the free blaxxun3D development 
kit. 
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3D worlds and the blaxxun Platform 

Using the blaxxun Platform one doesn’t have to care about the basic embedding 
of the Plugin or of blaxxun3D. The basic setting is already provided in the tem- 
lates “contact3d.html” and “bx3dchat.html” located in the folder “csbin/commu- 
nity/templates/place”. 

When creating a new chat place in the admin interface the appropriate folder is 
automatically created. It also contains a subfolder called “vrml”. The only thing 
the author has to do is to copy the vrml file into that folder and name it using the 
same name like the place. 
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About Avatars 

Avatars are figures that represent the user in the virtual environment. Technically 
they are VRML-files that are realised as Protos. Avatars may perform gestures. 
These are predefined animations that get started by an eventln. 

When a user enters a virtual world, his avatar file gets loaded on all other users 
machines. This replica of the user’s avatar is called drone. The drone gets send 
all actions the user starts and performs them locally on every client’s machine. 


Common rules for Avatar design 

For human Avatars we recommend using blaxxun Avatar Studio, which is distrib¬ 
uted with the blaxxun Platform. This tool is very easy to use and provides a very 
compact avatar file with a set of 10 gestures. However, there may be cases, 
where you don’t succeed using this tool. In theses cases you should be aware of 
the following rules, which should apply to your avatar: 

• Generally avatars should fit in a 1x1 x2m box to fit with the world propor¬ 
tions they get loaded into 

• Co-ordinate centre must be in eye height 

• No lights should be part of an avatar 

• Collision should be enabled 

• Only one texture file should be used 

• Complex animation should only be started if the avatar is visible (use Vis- 
ibilitySensor!) 

• In case of complex geometry Level Of Detail (LOD) should be used 

• The Proto must be named 'Avatar 1 

Besides these special rules for avatars the common rules for VRML design are 
valid for avatars as well and should be considered. (See “Design Rules” on page 
13) 

When loaded the avatar is placed with its co-ordinate center at the position of the 
first viewpoint in the scene. Though it is assumed, that the center of the avatar 
is at eye-height, the viewpoint should be about 1.75m above the ground plane to 
avoid the avatar being stuck in the ground. 





blaxxun Avatars - Proto Interface of a blaxxun Community Avatar 


Proto Interface of a blaxxun Community Avatar 

Avatars must be realised as Proto named ’Avatar’. In the case of not using 
blaxxun Avatar Studio to create avatars your avatar should implement the follow¬ 
ing Proto-interface: 

PROTO Avatar [ 

exposedField MFFloat avatarSize[ 0.25 1.7500 ] 

exposedField SFBool isAvatar TRUE 

eventln SFTime set_gesturel 

eventln SFTime set_gesture2 

eventln SFTime set_gesture3 

eventln SFTime set_gesture4 

eventln SFTime set_gesture5 

eventln SFTime set_gesture6 

eventln SFTime set_gesture7 

eventln SFTime set_gesture8 

eventln SFTime set_gesture9 

eventln SFTime set_gesturelO 

exposedField MFString gestureNames [""] 

eventln SFVec3f set_position 

exposedField SFRotation rotation 0100 

exposedField SFInt32 whichChoice 0 

exposedField SFBool isOver FALSE 

exposedField SFTime touchTime 0 

exposedField SFBool isPilot FALSE 

exposedField SFString nickname "" 

] 


field 

avatarSize 


isAvatar 


description 

contains the appropriate proportion 
for this avatar (collision radius, eye 
height, step over height) 

overwrites the appropriate field of 
the Navigationlnfo node the avatar 
gets loaded into 

necessary field for a community ava¬ 
tar 

indicates, that the file is a valid ava¬ 
tar with a complete Proto-Interface 
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set_gestureX 


set_position 


rotation 

whichChoice 


touchTime 


isPilot 

nickname 


blaxxun Avatars 



eventln to trigger gesture animation 

must be connected to the appropri¬ 
ate TimeSensor in the avatar imple¬ 
mentation 

eventln to move avatar geometry to 
the position the user is 

avatar receives current position from 
plugin, drone from server 
eventln to rotate avatar geometry 
according to the users rotation 
geometry must be set under a 
Switch node to switch it off when 
avatar is off view 

avatar should contain a TouchSen- 
sor to mark user in the user list of a 
community. This eventOut must be 
connected to this TouchSensor 
marks, if the file is the users avatar 
or its drone 
saves users nickname 


Avatars in blaxxun3D 

When creating avatars using blaxxun Avatar Studio automatically a version for 
use in blaxxun3D is exported. This file is named “someNamex.w\” and uploaded 
to the same directory as the standard avatar. 

When preparing the avatar manually you should follow these rules: 

• remove the Proto-Interface due Protos are not supported by blaxxun3D 

• remove all Script nodes due Scripts are not supported by blaxxun3D 

• remove all other unsupported nodes and fields. You may consider using 
the bx3DWizard to help you cleaning up the code. The wizard can be 
downloaded from the download section. 

The current implementation of blaxxun ContactLE, the pure Java MultiUser-Cli- 
ent does not support avatar gestures for performance reasons. Nevertheless it 
is possible to have fully animated avatars with blaxxun3D or ContactLE. An 
example where all vertex animation are calculated in Java and dynamically set 
in the avatar can be seen in the examples area. 


blaxxun 
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BLAXXUN SHAREDEVENTS 


Common VRML event handling only realizes a single user experience. This is 
because a VRML file always gets loaded locally and all events happen locally 
without any network distribution. This means for instance that if user A moves an 
object, user B will not notice that. To achieve a multi-user experience one needs 
so-called shared events. 


Principle 


To use shared events, two Protos need to be referred and instanced in the VRML 
world. They are called BlaxxunZone and sharedEvent and you’ll find them in 
the file shared.wri or on the blaxxun website http://www.blaxxun.com/vrml/pro- 
tos/shared.wrl . 

You may refer to the Protos via Externproto mechanism, but we recommend 
copying and pasting them at the top of the VRML world source code, to avoid 
loading problems with Externprotos. 

The BlaxxunZone proto mainly holds information and access to all avatars in a 
scene. SharedEvent realizes the multi-user event handling. Nevertheless you 
always need to instance both of them, because SharedEvent can only be 
instanced as a child of the events field of BlaxxunZone: 

DEF SharedZone BlaxxunZone { 
events [ 

DEF SharedColor SharedEvent {name "newColor" } 

DEF SharedRotation SharedEvent {name "otherEvent"} 


} 

One very important field of SharedEvent is the name. This is because on the 
server different shared events can only be distinguished by their names. That is 
why it is very important to name your shared events differently. 

The two mentioned protos work as an interface to the server. They work like a 
black box. So to realize multiuser action, you only need to know how to integrate 
them and how to change the event handling. The rest is done by blaxxun Contact 
and the Community Server. 

The main difference when integrating shared actions is the event routing. It 
changes as illustrated in the figures below. 
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Fig. 5: Shared event handling (local) 
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Fig. 6: Network-distributed shared event handling 

So instead of routing the events directly from the source to the destination, you 
have to change the routings from the source to the sharedEvent proto and 
from the SharedEvent proto to the destination. 


Functionality 

blaxxun Contact parses the VRML file when loading a scene and notices 
instances of the mentioned Protos. All events, that are routed to the SharedE¬ 
vent Proto are automatically send to the server and from there distributed to all 
clients. The sender of such an event also receives it this way as one client of the 
scene. 

One important fact when working with shared events is the network capacity. For 
capacity reasons, it’s only possible to send SF~ data via shared event. The 
SharedEvent-Proto has eventlns of all possible data types (named „set_fype“) 
and corresponding eventOuts named fype_changed. 
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It is very important NOT to send machine-dependent events over this interface, 
such as fraction_changed events from a TimeSensor, drag-events from a 
mouse, value_changed events from Interpolators or similar. These events are 
machine dependend and therefor fired as often as the local CPU can. Events of 
this kind would create an enormous amount of data, which would slow down the 
server immensively and possibly overload the receiving client. To avoid this mis- 
suse, blaxxun Contact will only distribute up to 3 events per second and ignore 
event cascades, that fire more often. If one wants to share an animation it is use¬ 
ful to send the initial event as a shared event, e.g. a TouchSensor.touchTime 
and compute the animation locally. 


An example usage of the SharedEvents is shown at this laptop. The trigger 
event for opening/closing the laptop is shared. Please note, that it is useful to 
review the example with two browsers or two different users, in order to notice 
the shared behaviour. The example is described in detail in the section “Exam¬ 
ples” on page 137 of the SharedObjectEvent. 


Persitent Storage 

Shared Events may be saved on the server. This way it is possible that users 
entering a scene after an event was sent, will still receive this event. This is nec¬ 
essary for instance if changed situations in the virtual world are of interest even 
for users entering this world later on. 

To use this mechanism, one simply has to give his SharedEvent a certain name 
in the name field of the SharedEvent. For that reason there are reserved abbre¬ 
viations available, which are used to indicate the desired persitent level. 

The following save attributes are supported: 

Don' t save the SharedEvent is not stored on the 

server. No naming rules apply 
(besides the fact not to use reserved 
names) 

As long as the scene is pop- the SharedEvent is stored as long as 
ulated there are users in the scene. If all 

users leave the scene, the SharedE¬ 
vent is deleted from the server. A 
users, who enters the scene after 
the SharedEvent was deleted will 
get the initial state of the world. 
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To use this attribute, name the 
SharedEvent: P_yoi/rA/a/77e 
(P=populated) 
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Forever the SharedEvent is stored on the 

server forever. This means, that 
users entering a scene will receive 
the last set value of this event inde¬ 
pendent whether the scene is still 
populated or not. 

To use this attribute, name the 
SharedEvent: F_yourName 
(F=forever) 

Creator the SharedEvent is stored as long as 

the creator of this event is in the 
scene. When the creator leaves the 
scene, this event is deleted. 

This type of persitence is especially 
necessary when imlementing differ¬ 
ent ’chat states’ of users, e.g. chang¬ 
ing the avatar for absence or when 
typing. 

To use this type name your Share¬ 
dEvent CRE_yourName 

Due this type makes scene in combi¬ 
nation with the dynamic creation of 
SharedEvents, you may as well read 
“Dynamic creation of SharedEvents” 
on page 145 


Access types 

The shared event-technology offers several possibilities, that may be useful in 
specific situations. There might be situations when you do not want to send 
shared events to all users or you do not want every user to send shared events 
etc. This functionality is realized by different access types of shared events. The 
following chapter will give a brief overview of these possibilities. 

Distribution 

SharedEvents of that type are NOT distributed to all clients, but only send to the 
server. This may be useful in combination with a special API server, that e.g. 
manages game scores. To implement this feature you have to name your shared 
event „_S_“, e.g. P_S_myEvent 
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Lock 

Lock is an access type of a shared event that allows the user, who has locked 
the event to send this event. All other users only receive values. 

The lock can be requested by sending any string via this shared event and can 
be cleared by sending an empty string („“). Lock is a good example for the dis¬ 
tribution" feature as well, because when one requests the lock, one doesn’t want 
to distribute this to all users but only ask the server to get the lock. The server 
will then answer with the nickname of the user you requested the lock or already 
has the lock and will automatically distribute this information to all users. The cre¬ 
ate a locked shared event you have to name your Shared Event „_LOCK_“ 

This example illustrates the use. 

If the lock is not set, you can set it by clicking on the red sphere. If you have the 
lock, you can release it by clicking on the green sphere. 

Pilot 

The access type Pilot is a special implementation of Lock. The difference is, that 
if the Pilot user leaves the scene, a new Pilot is automatically set by the server 
randomly. In the case of lock, the lock has to be requested again. 

To create a Pilot Shared Event simply name your Shared Event „_PILOT“ 

In the following example, the first user to enter the scene receives the Pilot Lock. 
If this user leaves, another user receives the Pilot Lock. If the user releases the 
lock by clicking on the green sphere, another user receives the lock. If there is 
no other user, the lock will go back to the user who had it before. 

Group 

If you want to distribute events only to a group of clients, but not all users which 
are logged in, one need to form virtual event groups on the server. To do this one 
has to implement 2 Shared Events, one to subscribe to or unsubscribe from a 
certain group (named „_S_GRP_SUBSCRIBE“) and one that realizes the group 
event (named „ _S_GRP“) 

To subscribe to a group, the user must send a string to the set_string event of 
the SharedEvent named “someName_S_GRP_SUBSCRIBE”. After subscrip¬ 
tion, the user will receive all events, that are sent through the SharedEvent 
named “someName_S_GRP”. Also events sent by this user via the “~_S_GRP” 
SharedEvent are received by all other users that are subscribed to this group. In 
order to unsubscribe from the group, an empty string must be sent to the 
set_string eventln of “someName_S_GRP_SUBSCRIBE”. 

Here is an example, which also uses History shared events (see next para¬ 
graph). You subscribe to 'red 1 or 'green' by clicking the respective box. Further 
clicking will send shared Events to the respective group. 
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Of course grouped events can be combined with the other access types for 
access and storage. 

History 

Using the above mentioned Persitent Storage mechanism it is possible to get the 
last send value of some SharedEvent. In cases when all send values are of in¬ 
terest, the History-Access type should be used. In this case a user will receive 
the queue of all values set for that shared event, not only the last one. For Group 
events he receives the queue after subscribing. 

To make use of this feature, name the SharedEvent using the substring 
“_HIST_”. 

Please note that history shared events require a proper application logic and 
enough system resources for the blaxxun Community Server. Especially persis¬ 
tent shared events need to be used very careful. We recommend to use _HIST_ 
events only if unavoidable e.g. if you cannot store the current status in a single 
shared event or when the time line of the event is absolutely necessary. Note 
that due the nature of the net, we cannot absolutely ensure that the user will 
receive the SharedEvent queue in the same order as it is sent (though for TCP 
connections it is very likely). 

This example uses group and history events. 

Reset 

In addition to the above mentioned type History, the Reset type may be used. 
Sending a set_string event to a SharedEvent named using “_RESET” as suffix 
resets the event queue for the shared event named 'eventname 1 . This means 
that you’ll need a second SharedEvent, that serves as a Reset-Controller for 
some other SharedEvent. These two events must share the same ’main name’. 

Setting a _GRP_RESET event to 'groupname' resets the shared event queue for 
the group ’groupname’ (see the subscribe event), that is the history of ALL 
grouped shared events. 

There is no inherent right or security mechanism on _RESET events, so your 
application should ensure that only authorized clients operate on them. You will 
usually use a PILOT or LOCK event to decide which client resets certain shared 
event queues. 

Empty 

This type is an extension to the different persitent levels. If an event, marked as 
’empty’ receives an empty string (““), the different persistent levels are not dis¬ 
tributed anymore. In other words, the empty string indicates to clear saved val¬ 
ues. In order to use this functionality name the SharedEvent “_EMP_”. Usage is 
recommended in order to save server ressources. 






Status 
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symbols a status event. This may be useful in order to distribute states of users 
for example when implementing advanced chat interfaces. The naming conven¬ 
tion here is: “_STAT_”. Basically this is the combination of a creator event with 
the empty extension: _STAT_ = _CRE_EMP_. 


Shared Events and ContactLE 


Shared events may be send and received in blaxxunContactLE. This may be 
used to share 2D events, for example in a presentation. However, a generic 
implementation of 3D SharedEvents for ContactLE is currently not available. The 
development has currently only proofed to be able to implement this feature in a 
project-specific manner. Here is an impressive example of this feature. 
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Principle 


Shared objects are objects that are used in a community context. They have sev¬ 
eral attributes regarding the community, e.g. price, quantity etc. 

To use shared objects in your community you have to prepare the VRML world 
that contains them. This VRML world must contain a special proto, the share- 
dobject proto. This proto realizes two different things. 

First, it is the connection to the database. From there all attributes like price or 
the position of the current instance in the virtual world are set directly in the 
VRML file. 

Second, it realizes an interface for each instance of an object. With this interface 
it is possible to move the instance for example in your shop or home world. 
Because the Proto knows about all attributes of the object it is also possible to 
create an own interface, that displays information like count, price, name etc. in 
3D. In that case you would have to override the interface implementation of the 
current sharedobject proto that you can find in the file home/vrml/sharedob- 
ject.wrl in you blaxxun Platform installation. 

If you want to use the currently implemented shared object mechanism, the only 
thing you have to do is to paste the sharedobject proto into the file that will 
hold your shared objects later on. When loading this world, blaxxun Contact will 
instance this proto for each object in the room automatically. 

The VRML file that serves as SharedObject must follow these design rules: 

• pay attention to the objects dimensions in regard to the dimensions of the 
world it will be displayed in, use common sizes like 1 unit = 1 meter to 
model your objects. 

• model your objects at the co-ordinate center with the ground plane being 
situated at y=0 (x/z-plane) and the object extending along the positive y- 
axis 

• please also consider the basic VRML design rules at “Design Rules” on 
page 13 
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SharedObject Proto 

The sharedob j ect proto is required to introduce shared objects into a commu 
nity and use them there. It: 

• provides the connection to the server and thus to the database. 

• provides an interface which makes it possible to position every instance 
of a shared object in 3D space. 

In order to use shared objects in communities, the VRML worlds that are to 
receive the objects need only reference the SharedObject proto. We recom¬ 
mend inserting the entire SharedObject proto at the beginning of the VRML 
world, and not referencing it via externproto. This is because it’s impossible to 
guarantee that the externproto will be loaded before the database information. 

If the SharedObject proto is contained in the file, blaxxun Contact can auto¬ 
matically instance the proto for every object that is loaded. 

Proto Interface 

PROTO SharedObject [ 

exposedField SFVec3f translation 000 
exposedField SFRotation rotation 0100 
exposedField SFString name "" 
exposedField SFString id "" 
exposedField MFNode children [] 
eventln SFBool startMove 
eventln MFString attributesFromServer 
eventOut MFString attributes_changed 
eventOut SFTime touchTime 
eventOut SFBool isOver 
eventOut SFVec3f newPosition 
eventOut SFRotation newRotation 
] 


Field 

Description 

translation 

The object’s position (as stored in the database) is 
set in the shared object instance via this field. 

rotation 

for setting the stored rotation of the object 

name 

for setting the stored name of the object 

id 

for setting the object ID 

children 

Through this parameter, the VRML file represent¬ 
ing the object is passed to the instance of the 
SharedObject proto via inline. 
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Field 

startMove 


attributesFromServer 

attributes_changed 


blaxxun SharedObject 



Description 

This event signals the beginning of a move action 
that can be started from the plug-in or from HTML. 
For this reason, the positioning interface (normally 
not displayed) must be displayed in preparation for 
this event. 

sets other object attributes 

connection from VRML to the database to write 

changed object attributes 


touchTime 


isOver 


newPosition 

newRotation 


The chapter “Database Access” on page 149 in the 
section “Dynamic 3D using the blaxxun Platform” 
provides more information on the connection 
VRML<->Database 

an Eventout to mark the object in the object list; 
requires a corresponding Touchsensor in the 
SharedObject proto 

an event used, for example, to mark an object 
when the user moves the cursor over it; requires a 
corresponding TouchSensor in the SharedOb¬ 
ject proto 

event for setting the changed position in the data¬ 
base 

event for setting the changed rotation in the data¬ 
base 


Positioning Interface 

The sharedob j ect proto includes an interface that can be used to position any 
object in the VRML world. These interface is implemented as a head-up display 
so that it remains constantly in the user’s field of view as he moves. This head- 
up display must be implemented in a switch node so that it can be turned on and 
off. 

DEF hudSwitch Switch{ 
whichChoice -1 
choice [ 

HUD{ 

children[ 

DEF interface_all Transform { 

#interface geometry 

} 


} 
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On a click on a positioning element of the interface (mouse button down), a 
TimeSensor starts. It runs in a loop as long as the mouse button stays pressed. 
When the mouse button is released, the TimeSensor is stopped. As long as the 
TimeSensor sends events, the object’s current position will be changed via a 
script. This action is only carried out locally; only when the action is confirmed 
with the OK button are the changed position and rotation data sent to the server 
and thus made visible to other users. A click on Cancel discards the local 
changes. This functionality is mostly provided by the mouseDownScript script 
node. 

Depending on the screen resolution, the hudPositioner function always posi¬ 
tions the interface at the lower right corner by calculating a factor from the aspect 
ratio of the 3D window and multiplying it with the x and y coordinates of the HUD. 
The HUD is simultaneously scaled independently of the resolution to keep the 
text as readable as possible. As a consequence, the display takes up proportion¬ 
ally more space in a small 3D window than in a large one. 


SharedObjectEvents 

If you want to design a shared object that has multi-user action, the object must 
contain a special proto called sharedobj ectEvent. Basically this proto is the 
same as the sharedEvent proto, but it contains several additional features that 
can be useful when working with objects. There are also certain limitations com¬ 
pared with the common use of shared events. 

The shop in the example platform worlds contains several objects which use the 
Sharedobj ectEvent proto. For example, users can position the chairs in the 
table set (/objects/tableset/atableset.wrl) and all other users will see that. The 
laptop (/objects/laptop/alaptop.wrl) performs shared open/close actions. They 
can also serve as examples for shared events in general, since the principle is 
the same. 


Additional fields of SharedObjectEvents 

In addition to all events and fields of the SharedEvent proto, the sharedob- 
j ectEvent proto contains the following fields and events: 

EXTERNPROTO SharedobjectEvent [ 
eventln SFString set_name 
eventOut SFString name_changed 
eventln SFString set_action 
eventOut SFString action_changed 
eventln MFString set_attributes 
eventOut MFString attributes changed 
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eventln MFString attributesFromServer 
eventOut MFString attributesToServer 
eventln SFTime set_touchTime 
eventOut SFTime touchTime 
eventln SFBool set_isOver 
eventOut SFBool isOver 
] 


These events override the events of the SharedObject proto. It is only useful 
to implement these events if you want to create a special HeadUpDisplay to 
move this certain object, or if you want to display attributes of the object in the 
object itself or anything similar. Please use them very carefully to make sure to 
achieve the result you want. 

Restrictions 

Some restrictions apply when using sharedObjectEvent. 

• You may only use ONE SharedObjectEvent per SharedObject 

• No advanced storage or access properties are available. 


Examples 


The following example describes the use of sharedEvent/sharedObject- 
Event. In the sample platform worlds, you’ll find a fil e /objects/Ia pto p/a la p- 
top.wrl. This laptop performs a multiuser open/close action. This means that all 
users in the scene can see the laptop opening/closing when any user clicks on 
the top of the laptop. 

At the very top of the file you’ll find the SharedObjectEvent proto. Note that 
in this case the proto doesn’t contain all fields, but only the ones that are really 
used in the file. This helps to decrease the file size and is therefore recom¬ 
mended. 

PROTO SharedObjectEvent [ 


eventln 

SFTime 

timeFromServer 

eventOut 

SFTime 

timeToServer 

eventOut 

SFTime 

time changed 

eventln 

SFTime 

set_time 

eventln 

SFBool 

boolFromServer 

eventOut 

SFBool 

boolToServer 

eventOut 

SFBool 

bool_changed 

eventln 

SFBool 

set bool 


exposedField SFString name "a" 
] 
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Script { 






eventIn 

SFTime 

timeFromServer 


IS 

timeFromServer 

eventOut 

SFTime 

timeToServer 

IS 

timeToServer 

eventIn 

SFTime 

set_time IS 

set_ 

_time 


eventOut 

SFTime 

time changed 

IS 

time 

changed 

eventIn 

SFBool 

boolFromServer 


IS 

boolFromServer 

eventOut 

SFBool 

boolToServer 

IS 

boolToServer 

eventIn 

SFBool 

set bool IS 

set 

bool 


eventOut 

SFBool 

bool_changed 

IS 

i—1 
0 
0 
13 

_changed 

url"j avascript: 





function 

set time 

(value, time) { 

timeToServer = value;} 


function timeFromServer (value, time) { time_changed = time;} 
function set_bool (value, time) { boolToServer = value;} 
function boolFromServer (value, time) { bool_changed = value;} 


}} 

We also recommend always pasting in the sharedEvent/sharedObject- 
Event proto at the top of the file. If you want to refer to it via externproto, be 
aware that you can’t rely on the loading of an externproto in time. 

Below this proto declaration you’ll find the instance of the proto: 

DEF laptop_close_event SharedObjectEvent{name "laptopl"} 

This is necesary to be able to use the proto at all. 

The laptop contains two TouchSensors, one at the top of the laptop to open it 
and one on the screen polygons to close the it. 

In order to share this behavior, the event routing has to be changed as follows: 

# shared event close 

ROUTE trigger_close.touchTime TO laptop_close_event.set_time 
ROUTE laptop_close_event.time_changed TO closeTimer.startTime 

# shared event open 

ROUTE trigger_open.isActive TO laptop_close_event.set_bool 
ROUTE laptop_close_event.bool_changed TO router.boolFromServer 
ROUTE router.startOpen TO openTimer.startTime 

Instead of having the route from the TouchSensor to the TimeSensor directly it 
is routed through the sharedEvent proto. This is why there is one Route from 
the TouchSensor to the set_time event of the SharedObjectEvent-Proto. And a 
second Route from the SharedObjectEvent-Proto to the TimeSensor. 
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For the close animation, three Routes are needed. In principle, the Routing 
would be the same as for the open animation. To use the time events of the 






blaxxun SharedObject 



SharedObjectEvent Proto twice for two seperate animations (open/close) two 
instances of this Proto would be needed. This would be possible if this was a 
common SharedEvent. But because this is a SharedObjectEvent, special limita¬ 
tions apply. In that case it is only possible to instance the Proto one time. 


This means, that for the second animation it is not possible to use the „set_time7 
“time_changed“ events of the Proto, but any other available event. In this case 
the „set_boolTbool_changed“ event is used. This fact makes it necessary to 
include a script. This script only converts the incoming boolean-event to a time- 
event: 


DEF router Script{ 
eventln SFBool boolFromServer 
eventOut SFTime startOpen 

url"j avascript: 
function boolFromServer(b, t) 

{ 

if (b) 

{ 

startOpen = t; 

} 

} 


} 


SharedObjects and ContactLE 

Please note, that 3d visualisation of SharedObjects is currently not supported in 
blaxxunContactLE (blaxxun3D). 
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BLAXXUN SHAREDZONE 


Principle 


For Multi-User-Environments blaxxun provides a Prototyp that should be imple¬ 
mented in all VRML worlds used in a Multiuser context. This prototype is called 
“BlaxxunZone” and can be found in the file “\htdocs\commserv\community\com- 
mon\proto.wrl“ in your blaxxun Platform installation or at http:// 
www. b I axxu n. co m/v r m I/p rotos/s h a re d. wr I. 

This Proto must be instanced using the ’reserved name’ SharedZone. No other 
name is valid, bacause blaxxunContact parses the VRML file for the existing of 
a node with that name: 


DEF SharedZone BlaxxunZone{ 
enabled TRUE 
} 

The Proto serves for different uses. 

Avatar information 

The Proto is automatically updated, whenever a user enters or leaves a commu¬ 
nity place. In cases you need to know about the avatar the the member is using, 
you can retrieve the desired information from the Proto. Information on retrieving 
avatar information is provided in the chapter “Retrieving avatar information” on 
page 147 

SharedObjects 

The Proto gets noticed about all SharedObjects, which are added to the current 
place. This may for example be useful to create an inventory list. 

It also contains a function, which is responsible for calculating the drop position 
for SharedObjects. You may override this implementation by your own function, 
but be careful doing so. 

Scene Changes 

When changing between community places, several processes of the blaxxun 
Platform check for the existence of this node in the current scene and use this 
node to make ’smooth’ scene changes. This means that it is usually not neces¬ 
sary to restart the plugin by simply moving from one 3d world to another. Restart¬ 
ing the plugin may be time consuming and may bother the user a lot, which is 
why it is recommended to avoid it. When building a 3d community without the 
SharedZone, a warning message is printed and the scene changes is made re¬ 
starting the plugin. 
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Container for SharedEvent 

The Proto also serves as a container for Shared Events. They must be instanced 
as children of the events field of the SharedZone. See “blaxxun SharedEvents” 
on page 125 for details. 


Proto Interface 

You may refer to the Proto by Externproto. But because you can’t rely on the 
loading of the node in time, this may be critical especially when trying to access 
information of the node at world startup. This is why we recommend inserting the 
whole Proto at the top of the current VRML file. 

The Proto interface of the BlaxxunZone looks as follows: 

PROTO BlaxxunZone [ 

exposedField SFBool enabled TRUE 

eventIn MFNode addEvents 

eventIn MFNode removeEvents 

eventIn MFNode addAvatars 

eventIn MFNode removeAvatars 

exposedField MFNode events [] 

exposedField MFNode avatars [] 

eventOut MFNode events_added 

eventOut MFNode events_removed 

eventOut MFNode avatars_added 

eventOut MFNode avatars_removed 

eventIn SFString set_myAvatarURL 

eventOut SFString myAvatarURL_changed 

eventln SFInt32 set_myAvatarGesture 

eventln SFInt32 myAvatarGestureFromServer 

exposedField SFNode beamToViewpoint NULL 

eventOut SFInt32 myAvatarGesture_changed 

eventOut SFInt32 myAvatarGestureToServer 

exposedField MFNode avatarLOD [] 

exposedField MFFloat avatarRange [] 

exposedField MFString sendToChat "" 

exposedField SFInt32 sendToChat Input -1 

exposedField SFFloat beamToDistance 3 

exposedField MFString groupChatName "" 

exposedField MFString groupChat "" 

exposedField SFString myAvatarName "" 

eventln MFNode addObjects 

eventln MFNode removeObjects 

eventln SFString set_action 

eventOut MFNode objects_added 

eventOut MFNode objects removed 
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eventln SFString beamto 
eventln SFBool calcDropPosition 
eventOut SFString dropPosition 
eventln SFString loadScene 


Field description 


enabled 


addEvents 


removeEvent s 


addAvatars 


removeAvatars 


events 

avatars 


events added 


enabled state of this node, is quer- 
ried by several community pro¬ 
cesses to check for the existence of 
the node 

if a SharedEvent node is sent to this 
eventln, automatically a SharedE¬ 
vent is instanced locally. However, if 
several users in a scene have done 
this, events distributed over this 
SharedEvent are shared between 
these users. For more information 
please also see “Dynamic creation 
of SharedEvents” on page 145 
if a SharedEvent node is sent to this 
eventln, automatically this SharedE¬ 
vent is removed locally, 
eventln is automatically called by the 
plugin whenever a user enters a 
scene. Query for avatars_added to 
hold an own list of all avatars in a 
scene. 

eventln is automatically called by the 
plugin whenever a user leaves a 
scene. Query for avatars_removed 
to update your own implemented list 
of all avatars in a scene 
holds all SharedEvents 
may be used to hold all avatars in a 
scene. NOT updated automatically. 
Please read the chapter “Retrieving 
avatar information” on page 147 for 
more information on this, 
is called whenever a addEvent event 
occured. Passes back the sent 
value. 
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event s_removed 

avatars_added 
avatars_removed 
s e t_myAva t a rURL 

myAva t a rURL_c hanged 
set_myAvatarGesture 

myAvatarGestureFromServer 
beamToViewpoint 

myAvatarGesture_changed 

avatarLOD 

avatarRange 

sendToChat 
sendToChatInput 

beamToDistance 


is called whenever a removeEvent 
event occured. Passes back the 
sent value. 

is called automatically, whenever a 
new user enters a scene 
is called automatically, whenever a 
user leaves a scene 
sets the new U RL for the own avatar. 
In a community context this only 
makes sense, if the avatarUrl is not 
set in the .bxx file, otherwise this set¬ 
ting doesn’t have any effect, 
is called by set_myAvatarURL 
may be called to trigger a gesture of 
the own avatar, 
called from plugin 
the given Viewpoint node receives 
the values for a beamTo action. 
Manipulating the fields of this View¬ 
point it is possible to correct the 
beamTo position for example for 
children avatars or to dissable 
beamTo at all. 

called after a set_myAvatarGesture 
event occured 

a node can be defined here, which is 
shown instead of some other users 
avatar, if the user is more distant 
than avatarRange to another user 

Useful for performance optimization, 
distance to other users in which their 
avatar is shown. If the current dis¬ 
tance is greater than the defined 
value, the node defined in avatar¬ 
LOD is shown. 

input text will be sent to the Public 
chat group 

receives character key codes as 
input event and writes the appropri¬ 
ate keys to the chat 
defines the distance between two 
users after a beamTo action 






groupChat 

myAvatarName 
addObj ects 


removeObj ects 


set_action 
obj ects_added 
obj ects_removed 
beamto 
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Incoming chat will be written to the 
exposedField groupChat 

automatically called when a Share- 
dObject is loaded into the current 
world 

automatically called when a Share- 
dObject is removed from the current 
world 

called from community processes to 
trigger special SharedObject actions 
called when a SharedObject is 
loaded 

called when a SharedObject is 
removed 

called from community processes to 
beam to a SharedObject or to beam 
to another user. 


Dynamic creation of SharedEvents 

As seen the BlaxxunZone provides events for dynamic creation of SharedE¬ 
vents. The following paragraph illustrates the usage of this feature. 

When sending a SharedEvent node to the addEvents eventln the SharedE- 
vent is at first only created locally. This means that only the communication unit 
of blaxxunContact has registered for this event. As a signal for the completion of 
this action the value is passed back through the eventOut events_added. 
Querrying this event, one may add the desired Routes to ’feed’ the created 
SharedEvent. Note, that in the standard version of the BlaxxunZone the node is 
not automatically added to the field events. An own implementation may over¬ 
ride this. 

After the SharedEvent is created and the Routes have been added, one may 
send events through this SharedEvent. However the send values are not 
received by other users in the scene until they have completed the creation pro¬ 
cess locally. One may think about triggering this process by another SharedE¬ 
vent, but this is a matter of implementation. Also in a game scenario one may 
think about situations were every game player has to complete a certain task 
until events are shared and therefor Multiuser actions are possible. 
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The following Sourcecode example illustrates the just mentioned behaviour. 
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DEF seObserver Script{ 
eventln SFTime touched 
eventIn MFNode eventsAdded 
eventln SFInt32 intFromServer 

field SFNode sz USE SharedZone 

field SFInt32 counter 0 

field SFNode insertedSE Group{} 

field SFNode thisScript USE seObserver 

eventOut SFInt32 intToServer 

url"vrmlscript: 
function touched() 

{ 

counter++; 
if(counter < 2) 

{ 

//create a new SharedEvent using createVrmlFromString 
newSE = Browser.createVrmlFromString('DEF se 
SharedEvent{name \"someSE\" }'); 

//sending this node to the SharedZone 
sz.addEvents = newSE; 

} 

else{ 

intToServer = counter; 

} 

} 

function eventsAdded(v, t) 

{ 

//holding a local reference to the inserted SharedEvent 
insertedSE = v[0]; 

//adding a Route from the SharedEvent to this Script 
Browser.addRoute ( insertedSE, 'int32_changed', thisScript, 
'intFromServer' ); 

//adding a Route from this Script to the SharedEvent 
Browser.addRoute( thisScript, 'intToServer', insertedSE, 
'set_int32' ); 

} 

function intFromServer(v, t) 

{ 

print('received integer :'+v); 


} 
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#Route from a TouchSensor to the Script to trigger the action 
ROUTE boxTouch.touchTime TO seObserver.touched 
#Route from the SharedZone to the script to get notified 
ROUTE SharedZone.events added TO seObserver.eventsAdded 


Retrieving avatar information 

As stated before the field avatars of the BlaxxunZone is not updated automat¬ 
ically for performance reasons. Nevertheless the avatars_added and 
avatars_removed event is calledwhenever a user enters or leaves a scene 
and therefor his avatar is added/removed to/from the world. The value of this 
event typically is the avatar node used by this user. However, in cases you need 
to have more control about the avatars in a scene, you must be familiar with the 
insertion process of the avatars and how to retrieve the desired information. 

Avatars are always loaded to a blaxxun community place in three steps: 

1. the default avatar is inserted 

2. a fallback wrapper is inserted 

3. the ’real’ avatar is fetched from the given avatar URL 

Because of that, for each correctly fetched avatar the event avatars_added is 
called three times. With the knowledge of that, it is possible to write script nodes, 
which can connect to the inserted avatar and control certain fields. The following 
code from a script, shows how to traverse the given value until the avatar node 
is reached. 

function addAvatars(v, time) 

{ 

for(i=0;i<v.length;i++) 

{ 

tempNode = v[i] ; 
if ( tempNode ) 

{ 

if (tempNode.children_changed[0] ) 

{ 

tempNode = tempNode.children_changed[0]; 
if( tempNode.getType()== 'Inline') 

{ 

if(tempNode.children_changed.length > 0) 

{ 
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tempNode = tempNode.children_changed[0]; 
if ( tempNode.getType() == 'Avatar' ) 
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} 


{ 

//tempNode now contains the inserted avatar node 

} 

} 

} 

} 

} 



blaxxun SharedZone and ContactLE 

As the SharedZone is a PROTO and Protos are not supported by blaxxun3D the 
SharedZone and all its functionality is not available in blaxxun ContactLE. This 
also effects functionality like beam to another avatar (beamTo) due this is real¬ 
ized by the SharedZone. 
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Dynamic 3D using the blaxxun Platform 


Usually VRML worlds are downloaded to the local harddisk and played there. 
Using the blaxxun SharedZone and blaxxun SharedEvent one can even share 
events over the network and achieve complex Multiuser interaction on an easy 
way. However, in a Community context it is often useful to create dynamic 3d 
content, which behaves in dependance to several user settings. For example it 
may be useful if the door to the mayors office can only be opened by the the 
mayor and is not active for all other users. In these cases one needs access to 
the database to query certain attributes and start diferent actions in dependance 
to that. The following chapter describes two diferent ways to achieve this. 


Database Access 

Usually in the blaxxun Platform the database is accessed by printing an html 
template using the print server script. This server process prints the desired tem¬ 
plate and checks for the existence of a config file with the same name. If existent 
the database is accessed using the commands from this config file. When print¬ 
ing, the template is filled with the returned database values. 

In order to use this mechanism in VRML, one simply has to print a VRML file by 
the mentioned process. The principle is as follows: A Script node in the VRML 
file calls the appropriate cgi script using the method createVrmIFromURL. The 
print script returns the desired node, filled with the database variables to the 
given function. This function must evaluate the values and do further processing. 

CGI-Call in createVRMLFromURL 


s = M /csbin/community/print?TPL=vrml_dbaccess/opn"; 
createVrmIFromURL(s,myself,'nodesLoaded'); 


Template: vrml_dbaccess/opn 

EXTERNPROTO DBAccess [ 

exposedField SFString opn 
] "../../common/dbaccess.wrl" 

DBAccess { 

opn "< $OPN>" 

} 
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Config-File of Template vrml_dbaccess/opn 

*GET M ID <$MEM_ID> OPN OPN 

If the action was successful, the node DBAccess is returned to the function 
’nodesLoaded’ containing the desired database value in the field ’opn’. 

Note that database values should always be handled as strings and converted 
to another datatype afterwards if needed . 

Database Access with SharedObjectEvent 

When working with SharedObjects, there is another database connection avail¬ 
able, because every SharedObject may have own database attributes, like price, 
quantity but also additional information. 

In order to use these attributes in 3D one has to use and possibly modify the 
SharedObjectEvent node. This node provides events which automatically 
enable a connection to the database. These events are called attributesTo 
Server and attributesFromServer . Using the above mentioned syntax 
for accessing the database it is possible to querry certain attributes. The follow¬ 
ing example illustrates the use: 

function initialize() 

{ 

attributesToServer = new MFString('GET','ID','DOC','OWN'); 

} 

function attributesFromServer (value, time) 

{ 

for (i = 0 ; i < value.length-1 ; i += 2) 

{ 

if(value [i] == 'DOC') 

{ 

docPath = value[i+1]; 
break; 

} 

} 

} 

As you can see, the original database call ’ get so id doc doc own own ’ 
was translated into several single string values of an MFString eventOut. 

The database table is left out as only the ’SO-Table’ (SharedObjects) is available 
from this interface. Also no target variable is given, because the return value is 
directly returned as an MFString eventln to the proto. The associated eventln is 
called attributesFromServer and the database values are automatically passed 
to this event. 
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More information on SharedObjects and the SharedObjectEvent Proto is avail¬ 
able in the chapters “SharedObject Proto” on page 134 and “SharedObject- 
Events” on page 136 


VRML as templates 

Another option is to have the entire VRML file being printed by the community 
print script. In that case, the VRML file is structured like a community template 
using the template syntax. Please read the chapter “Template Syntax and Data¬ 
base Access” in the Reference Manual of the blaxxun Platform for details on this. 
Typically the CGI script generates a small main file, which uses parametrized 
external protos or inlines. The advantage of this approach is that these inlines 
and protos can be static files that can be cached. 

This approach is best suited, if the database content shown in the VRML does 
not change while the user is in the scene. A typical scenario is the display of texts 
in the VRML file depending on the user language, or depending on his role. 

If the data changes dynamically, you additionally need 

• a CGI call which modifies the database (see sub section above) 

• a shared event in the generated VRMLfile which distributes the changes 
to the other users in the scene and which is routed to the corresponding 
parameters of the external proto. 

In any case you have to change the parameter ”3dscene” in the template 
”3dchat.bxx” to call the CGI script ’’print” to generate the VRML file from a tem¬ 
plate. See also the chapter “Plugin Chat” in the blaxxun Platform Reference 
Manual. 

The following source code extract illustrates the usage of the blaxxun Template 
syntax in combination with VRML content: 

<-- #if variable="PLC" = = value="someplace"--> 

Inline{ 

url"inlinel.wrl" 

} 

<-- #else variable="PLC" --> 

Inline{ 

url"inline2.wrl" 

} 

<-- #endif variable="PLC" --> 


blaxxun 


When printing the template, the condition is reviewed and in dependance to the 
result only the valid block is processed. In this case online if the user is at a corn- 
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munity place called “somePlace” the VRML Inline “inlinel .wrl” is loaded. In all 
other cases “inline2.wri” is loaded. 
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blaxxun Contact 
JavaScript-EAl 

blaxxun Contact 3D (release 3.07 or higher) supports an easy-to-use external 
scripting interface for Javascript and VBScript. It allows to read and write any 
fields values of named nodes. String input values are converted automatically to 
the appropriate field types. Additionally VBScript (in Internet Explorer) and Jav¬ 
ascript (in Netscape) methods can be called from internal VRMLScript script 
nodes. 

Browser reference 

In order to effect the 3d scene you need to obtain a reference to the VRML 
browser. You can access the plugin using the name which is specified in the em¬ 
bed tag, respectively the ID specified in the object tag. Please see “Embedding 
blaxxun Contact” on page 111 for details on these parameters. 

Supported JS calls 

The following calls are available for interfacing blaxxun3D via Javascript: 


setNodeEventIn 
(String nodeName, 

String eventInName, 
String value) 
getNodeEventOut 
(String nodeName, 

String eventOutName) 
OnNextViewpoint() 

(InternetExplorer only!) 
setNextViewpoint() 

(Netscape only!) 


set the value for the specified even- 
tin of the named node converting 
value to the type of the eventln 

returns the value of the eventOut 
converted to a string 

activates the next Viewpoint in the 
Viewpoint stack 

same function as above, but 
Netscape only! 


Accessing Javascript from VRML 

It is possible to access any Javascript-Function in HTML from a VRML file. Using 
the following call in an Anchor node or in a Browser.loadURL call in a script ac- 
esses the specified function: 
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"javascript:myJSFunction() 

If the specified function is declared in an HTML document in another frame, the 
target must be specified using the parameters field of the Anchor or the second 
parameter in a Browser.loadURL call. See example code below for details: 

Example 1: Calling a JS-Function by an Anchor 

DEF anchor1 Anchor{ 

url"j avascript:externalFunction() ;" 
parameter["target=_self"] 
children[ 

#some geometry 

] 

} 


Example 2: Calling a JS-Function from a Script 

Script{ 

field MFString param ["target=someFrame", ""] 

eventln SFTime touch 
url"vrmlscript: 
function touch() 

{ 

Browser.loadURL('j avascript:externalFundtion() ', param) ; 

} 

II 

} 


Java-EAI 


Overview 

The VRML 2.0 Java EAI allows a Java applet to control a VRML97 plugin, run¬ 
ning on the same HTML page. The applet can use java user interface elements, 
threads, sockets etc. The applet can interact with the VRML world in the follow¬ 
ing ways : 

• Accessing the functionality of the browser interface (eg to create new ge¬ 
ometry) 

• Sending events to eventlns of nodes inside the scene, (eg to change po¬ 
sitions or colors of objects) 

• Reading the last value sent from eventOuts of nodes inside the scene, (eg 
to find the last position of an object) 

• Getting notified when events are sent from eventOuts of nodes inside the 
scene, (eg when an object is being clicked) 
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blaxxun Contact 3D supports the proposed VRML 2.0 Java EAI interface. 
Besides that there are additional methods available, for further developing the 
EAI capabilities. 

API reference 

The full documentation of the supported EAI calls can be found at here 
blaxxun enhancements 

Besides the above mentioned calls, blaxxun Contact provides the following ad¬ 
ditional methods on vrml.external.Browser. 

Please note that these are all blaxxun Contact 3D extensions. If you decide to 
use them your application should perform a browser check to avoid trouble with 
other VRML browsers. 


General methods 

public static Browser 
getBrowser (Object object) 


public static void 
SetControl (Object object, 
java.applet.Applet pAp- 
plet) 


public static void FreeCon- 
trols () 


Access to world and navigation 

public String getViewer- 
Mode() 

public void setViewer- 
Mode(String navigation- 
Mode) 


return an instance of the Browser 
class 

Netscape : This returns the first 
embedded plugin in the current 
frame. 

IE : call setControl(handleOfVrml- 
Control) first or use getBrowser(han- 
dleOfVrmlControl) 
set the control object 
(blaxxunCC3D) used for Internet 
Explorer: input is handle to 
blaxxunCC3D Active X Control 

Netscape : not supported 
free the control object 
(blaxxunCC3D) 

Netscape : not supported 


Get the name of current navigation 
mode (walk, examine, fly ...) 

Set current navigation mode (walk, 
examine, fly ...) 


blaxxun 
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public String getView- 
point() 

public void setViewpoint 
(String viewpointName) 
public void saveViewpoint 
(String viewpointName) 


public boolean 
getCollisionDetection() 
public void 
setCollisionDetection 
(boolean collisionDetec) 
public boolean 
getHeadlight() 
public void 

setHeadlight(boolean head¬ 
light ) 

public boolean 
getanimateAHViewpoints () 
public void setAnimateAll- 
Viewpoints(boolean ani¬ 
mat eAll Viewpoints) 
public void 
setNextViewpoint() 
public void 
setPrevViewpoint() 

Methods to improve performance 

public void beginUpdate() 


public void endUpdateO 


set new viewpoint by string 

Save viewpoint. If viewpointName 
node not present, a new Viewpoint is 
created and the current camera 
position is used to initialize its fields 
Get current state of the Collision 
Detection 

Set blaxxun Contact3Ds collisionDe- 
tection 

Get state of blaxxun Contact 3Ds 
headlight 

Set state of blaxxun Contact 3Ds 
headlight 

Get state of blaxxun Contact3Ds 

animateAllViewpoints 

Set state of blaxxun Contact 3Ds 

animateAllViewpoints 

Jump to next viewpoint 

Jump to previous viewpoint 


Notifies the browser of a batch of 
EAI operations requiring no render¬ 
ing cycles in between eg setting the 
translation AND rotation of an object 
before rerendering. A call of begin¬ 
Update must be followed by endUp- 
date. You may nest begin/end 
update calls. 

Ends the batch of EAI operations 
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public int setTimerlnter- 
val(int milliseconds) 

Sets browser timer animation cycle 
in milli seconds, the old timer interval 
is returned to enable resetting it. 

Useful to reduce system load ( 
greater numbers 200 - 500), or get 
more frequent updates (lower num¬ 
bers 10 - 100 ). 

Note: the timer interval resolution is 
limited by operating system and pro¬ 
cessor load. 

Important: Do not use this call in a 

Contact environment 

Node and scene access 

public void addNode(Node 
newNode) 

throws 

I1legalArgumentException 

public boolean removeNode 
(Node removeNode) throws 

I1legalArgumentException 

Adds newNode as a new top level 
scene node. 

Removes removeNode from top- 
level scene node. Returns true, if 
removeNode was a top level node, 
and was successfully removed. 

public Node createNode 
(String name) throws 
InvalidNodeException 

Creates a node of the given node 
type (name) or prototype. A simpler 
alternative to createVrmlFrom- 
String( M name {}"). 

public void setNodeName 
(Node node, String newName) 
throws 

I1legalArgumentException 

Example 

createNode("lnline M ) 

Sets the name of node to newName. 

Afterwards the node is available 
afterwards via getNode(newName). 

The application is responsible, that 
the node is or will be part of the cur¬ 
rent scene. 

public Node getWorldO 
throws IllegalNodeExcep- 
tion 

Returns the top level blaxxun Con¬ 
tact 3D scene group node, holding 
the VRML world (aka root node). 

Starting from the root node you may 
parse the scene graph via its MFN- 
ode/Eventout "children" to access all 
top level nodes. 157 
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public void replaceWorld 
(Node node) throws 
I1legalArgumentException 
public EventOut 
adviseOnUrlChanged 
(EventOutObserver 
observer, Object userData) 


public boolean saveWorld 
(String fileName) 


Replaces the current world with the 
passed node. Note: the passed 
node has to be a "Scene" node 
sets an EventOutObserver for the 
urIChanged event. You are notified 
whenever a new scene is down¬ 
loaded and was successfully 
parsed. The type of the returned 
EventOut is SFString, its value is the 
URL of the world. 

Note: this is a global event, so you 
just need to subscribe once. Use it if 
you have several vrml scenes con¬ 
nected via anchors but want to use 
the same controlling applet. 

Saves the current VRML world to a 
local file, especially useful for 
debugging dynamically created 
worlds. fileName must be the name 
of a local file. 
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Accessing nodes and events 

We suggest using the following template to retrieve node handles, it connects 
to blaxxun Contact 3D in two steps: 

1 . poll until the browser handle is retrieved. 

Reason: NS/IE do not necessarily start the VRML browser before/ at the 
same time as your applet. 

2 . once you got the browser handle poll until you retrieve all needed node 
handles. 

Reason: The getNode call above fails, if the VRML world was not com¬ 
pletely downloaded or parsed, a solution is to delay or better ( as here ) 
repeat the getNode() call until it is successful. 

Step 2. is especially important in a multi-user environment: blaxxun Contact con¬ 
trols via multi-user parameter file (bxx) which URLs are loaded in 3D. This 
means even if you specify the VRML world as a parameter in the 3d frame, 
blaxxun Contact 3D will not load the VRML world until the multi-user connection 
is up. 

Note: If you do not supply the VRML world as a blaxxun Contact (bxx) parameter, 
it will not be loaded at all (see blaxxun Platform Documentation). Therefore poll 
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until you retrieve the nodes you intend to use, additionally you may poll for the 
VRML world blaxxun Contact 3D has currently loaded ( Browser.getWorldUrlQ). 


We encourage you to have a close look at the EAlConnect.java source and the 
several comments it contains. Click here to download/open a complete zip file ( 
containing the blaxxun Contact frameset, EAlConnect class file and source, and 
a VRML file), extract it to an http path, and open the index.html file. 


The EAI and shared events 

As blaxxun SharedEvents are VRML nodes, you may access, send and retrieve 
them using EAI. So you could: 

• start animation or modify objects or scene properties with a button click 
for all visitors of the world 

• share an event, read only by your EAI application, which then starts a 
complex scene manipulation. 

• Provide a user interface for your visitors to share information, eg type an 
URL which then is shown to other visitors. 

Shared.java is a simple applet that passes JavaScript calls to the EAI to send 
shared events. Please note that as the JavaScript does not know about blaxxun 
Contact 3Ds status, clicking the links will not work until blaxxun Contact 3D is up 
and running. Again here is a complete zip file containing the blaxxun Contact 
frameset to put this example on an HTTP server. 

If you encounter problems connecting your applet to the VRML Browser over dif¬ 
ferent frames, you may try t use the following VBScript code to set the Browser 
reference. 


<script language=VBScript> 

< ! -- 

Sub window_onLoad 

document.vrmlApp.setBrowser browser 
end sub 
! - - > 

</script> 

Note that in this example the plugin ID is ’browser’ and the applet ID is ’vrmlApp’. 
If you use different names, you have to adjust the call. 

Common Problems and Troubleshooting 

The two most common problems with EAI applications are VRML browser set¬ 
ups ( aka classpath problems) and timing issues. If blaxxun Contact 3D was the 
last installed browser, you should be fine, as blaxxun tries to take care of these 
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problems. However, if you did install another browser afterwards the EAI most 
likely will work in neither browser. 

If you discover problems, try the following steps: 

• Check whether blaxxun Contact is installed properly. The following files 
should be present in the $(WINDOWS)\java\classes and in the 
$(NetscapeAppPath)\java\classes directory 

vrml\external\*.* - VRML97 EAI classes for blaxxun Contact 3D 

The following files should be present in the $(WINDOWS)\java\class- 
es\trustlib directory if the EAI is being used 

blaxxxuncc3d\\* - blaxxun Contact 3D COM Browser interface 
blaxxunvrmlW - blaxxun Contact 3D COM VRML interface 

• If you are using IE4.0x or 3.Ox with an updated Java VM please check the 
registry key 

HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/JavaVM/. 

This is where IE looks for java classes. It should read 
$ WIN DI R\j ava\c lasses 

first. If not move it to first place, and remove other entries referring to 
VRML EAI implementations mainly msvrml.zip and avWorldview.zip . 

• For Netscape check the classpath variable in your autoexec.bat (WIN95) 
respectively in your NT system environment. 

Preferably it should be empty, but it is sufficient to remove all references 
to an EAI implementation eg npcosmo.zip, npcosmo.jar, npcosmo21 .jar. 

In both cases you need to reboot to make your changes effective. 


COM Interface 

Overview 

blaxxun Contact 3D is an ActiveX Control designed from the start to expose all 
application relevant features and give superior control over the browser. Any ap¬ 
plication capable of embedding OLE Controls can create, use and control 
Contact3D for VRML applications ( e.g. a virtual mall) or to have a cheap and 
easy 3D engine eg to visualize data sets in an OLE application eg Powerpoint ( 
Note, you should implement an ActiveX document server for this). 

Hint: The control has still the former name blaxxuncc3d.ocx 

Features 

• Complete support for Microsofts ActiveX standard, therefore accessible 
with all COM capable languages eg VC++, Java, Visual Basic and VB¬ 
Script. Contact 3D is an in-process COM server. 
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• Complete EAI available via COM calls. 

• Superior observers and callbacks to retrieve Contact3D signals and re¬ 
sume control over browser actions eg. load another Url. 

• Extensions to VRML97 events to retrieve and set user and world informa¬ 
tion. 


How to start 

Before starting the developer should get a basic understanding of VRML97, the 
EAI proposal and especially Microsofts COM model. The following examples are 
all based on VisualC-H-, and were created with MS VisualC++ 5.0 (recommend¬ 
ed version 4.2 and up), they should translate easily to VisualBasic. Though de¬ 
velopment with Java is possible, we recommend using blaxxun Contact3Ds EAI 
for Java instead. It is an almost complete mapping of Contact3Ds COM interface 
and sufficient for most applications. 

To start add blaxxun Contact 3D to an existing project in Developer Studio. Open 
or create a new MFC or ATL project. Add blaxxun Contact 3D by selecting 
M Project M -> M Add to Project M -> M Components and Controls" -> "Registered ActiveX 
Controls"->"blaxxuncc3d". 

DeveloperStudio will create a wrapper class ( usually CblaxxunCC3D), defining 
member functions for all browser methods supported by blaxxun Contact3D. 
This is a very important file for the COM programming, so be sure to have a close 
look at it (annotated version). The other file you definitely should take some 
time to study is the IDL source for blaxxun Contact3Ds VRML external API con¬ 
taining the supported interfaces for Nodes, Fields, Events and Contact 3Ds 
browser observer. 

With the wrapper you can insert blaxxun Contact 3D into dialogs like a standard 
button. The Cblaxxuncc3d.Create method can be used to create a specific 
instance. Nodes and Events can be accessed by querying the IUnknown Point¬ 
ers from blaxxun Contact3D for the interface Node as defined in blaxxunVRML.h 

Active Template Library (ATL) 

If you have done some COM development, you probably have suffered a lot us¬ 
ing beasters (BSTRs) and mapping interface pointers. ATL provides a huge 
amount of templates to make the programmers life easier, most notably default 
implementations for COM objects(eg CComObjectRoot) and 'smart 1 interface 
pointers (eg CComQIPtr, CComBSTR). Using ATL can save you a lot of devel¬ 
opment time. If you do not start from an ATL project anyway, you can easily in¬ 
clude it later. 
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Contact3D parameters 

It is of high importance that for all COM objects you use to communicate with 
Contact 3D you maintain a proper reference count. Always release the reference 
before destructing the COM object, and if you are using ATL consider the auto¬ 
matic AddRef/Release calls the templates do. 

Note: Reading a value of a VRML node usually does not do an automatic Ad- 
dRef, unless you are retrieving node handles eg a children of an MFNode. To 
avoid memory leaks you nead to release these pointers manually before de¬ 
structing or changing them. If you retrieve values of EventOuts you usually have 
allocate the memory space for the values ( eg by supplying a pointer to a float 
variable). However this is not possible for values of unknown size that is all 
MFFields,SFString and SFImage. In that case Contact3D allocates the space for 
you, so make sure that you free it afterwards. 

VRML extensions 

In addition to the EAI EventOutobservers blaxxun Contact 3D provides the fol¬ 
lowing VRML extensions: global observers, usage browser.setObserver( ob¬ 
server,flags), see blaxxun Contact 3D.h. where flags in any combination of these 
flags (defined in the Contact 3D ODL file, respectively blaxxuncc3dlnterface.h): 

• OBSERVE_MESSAGE 

sends Contact 3D status messages to you instead of the browser 

• OBSERVE_ANCHOR 

observes anchor clicks and skips automatic loading of that anchor url. If 
you use this observer you have to tell Contact3D to load the appropriate 
anchor url ( via browser, load Url) 

• OBSERVE_VIEWPOINT 
observes the current camera position. 

• OBSERVEJJRLLOADING 

puts you in charge of loading urls (if you really want to ). 

• OBSERVEJJRLERRORS 

tells you, which Urls could not be loaded successfully eg image textures. 

Please see also the the chapter “Browser object extensions” on page 32 and the 
chapter “Node Extensions” on page 51. The annotated blaxxuncc3d.h file 
gives additional information as well. 

Implementation issues 

As the multi-user part of Contact uses Contact3Ds COM interface in the same 
way as your application, programming for this environment requires great care. 

• performance 

Any 3d application already puts a hefty price tag on system resources. 
With Contact in multi-user mode already running as 2 separate threads in 
the internet browser, your application should be optimized regarding sys¬ 
tem load. 
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• begin/endUpdate 

Usage of the beginUpdate method freezes the browser until the closing 
endUpdate call. As Contact uses this call too, you should minimize ac¬ 
tions within such a block, or better not use it at all. ( see “Java-EAI” on 
page 154 for details on these calls) 

• Call backs 

All observer calls from Contact3D are blocking, so you should move big¬ 
ger call back actions to your next timer cycle. 

• Special Observers 

All global observers from the previous paragraph are used internally in 
multi-user mode too. The code allows for several observers but any addi¬ 
tional one will slow down Contact. 

• Shutdown 

In the multi-user environment Contact3D may shutdown before or after 
your application. This imposes some problems for the COM objects 
through which you communicate with Contact3D. Though you still have a 
reference to the COM object, releasing it crashes occasionally in current 
internet browsers, which of course it should not. This would be solved by 
the Initialize/Shutdown method proposed for the EAI. Unluckily its usage 
is currently unclear and therefore not yet part of the COM interface. As a 
workaround Contact3D sends an OnLoadUrl( NULL, NULL) notification to 
its observers before shutting down. Once your observers receive this no¬ 
tification they should release all COM objects retrieved from Contact. 

• Connecting to Contact3D 

In the multi-user environment you may not instantiate your own 
Contact3D, but have rather to connect to the one created by the internet 
browser. Therefore you have to search the browsers window hierarchy for 
Contact3D. The following code fragment shows how it is done ( where 
Cblaxxuncc3d is the generated wrapper class and parent is a window in 
the hierarchy): 

Cblaxxuncc3d* FindClass::FindContact3D(HWND parent) 

{ 

HWND Contact3DWnd = NULL; 

Cblaxxuncc3d *Contact3D=NULL; 

LPUNKNOWN browser=NULL; 

if ((Contact3D = (Cblaxxuncc3d*)::GetProp(parent, "CC3D")) != 
NULL) 

{ 

return Contact3D; 

} 

} 

Alternatively you could just use Contact3Ds IDispatch interface, as the internet 
browser already takes care of creation and destruction of Contact3D: 
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if ((browser = (LPUNKNOWN)::GetProp(parent, "CC3D_LPUNK")) 

!= NULL) 

{ 

// and get dispatch interface 
CComQIPtr browserdp(browser); 

// init the smart pointer Contact 3D object 
if (browserdp) 

{ 

m_browserValue.AttachDispatch(browserdp); 
return &m_browserValue; // Contact 3D controller uses -> 

} 

} 

or do it the official way, getting the contained IUnknown object from a CWnd 
object, and then retrieve the Query Interface using the I IDs as supplied in 

blaxxunVRMLJ.c. 

COM Interface Reference Information 
blaxxun Contact3D Control ODL interface 

Study this file for browser access. If you do not feel comfortable reading this file, 
study “Examplel” on page 164 first or try the wrapper file instead. 

blaxxun Contact3D VRML IDL interface 

Study this file for Node, Event and Field access and how to define a browser 
observer. For EAI like applications and all VRML access this file is very impor¬ 
tant. If you do not feel comfortable reading this file, study “Example2” on page 
165 first and then return to this file. 

Annotated header file for the wrapper class as generated by Developer Studio 
Please have a close look at this file ! 

blaxxun Contact3D VRML include file from C/C++ 

For Node and Event access you have to include this file 

blaxxun Contact 3D interface generated from ODL file. 

Implementation file for the wrapper class as generated by Developer Studio 

Include file for Contact3D IID constants as generated by Developer Studio, 
needed for ATL smart pointers. Note: Do not compile this file, just include it 

Examples 

Examplel 

MFC standalone single document application embedding the blaxxun Contact 
3D Active X Control into the program. 

Features : Opening, viewing, browsing and saving of VRML files. Opening of 
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VRML URL’s. 

Development time : 1.5 hours 

Developer Studio 5 Project File, MFC-Source code and ready to run compiled 
application : download. 

The ReadMe.txt in the zip file contains additional comments. 



Example2 

An EAI application dynamically modifying and observing the VRML scene graph. 
This example uses the Active Template Library to create some helper classes. 
The sample code creates and adds geometry to the scene, and observes a dy¬ 
namically added TouchSensor with an eventOutObserver. 

download. 

Resources 

There are thousands of COM resources on the net, a good place to start for all 
kinds of COM references ( SDKs, links, books ) is Microsofts own COM site 

You might want to check out their news server too. 

The VRML EAI provides a description for most Contact3D COM calls. 

And of course the VRML97 spec. 
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To raise the level of interactivity and to extend blaxxun3D’s functionality toward 
desired but yet unimplemented features there are two ways of interfacing 
blaxxun3D: 
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• via a second java applet on the same HTML page 

• via javascript calls 



JavaScript-EAl 

Javascript calls might be preferable because they're easy to use. No compiling 
and no deep understanding of programming itself is needed. Javascript makes 
it possible to add simple interaction between blaxxun3D and other elements on 
the HTML page. 

Browser reference 

In order to effect the 3d scene you need to obtain a reference to the browser ap¬ 
plet. You can access this applet by the name you have specified in the applet 
tag. Please see “Embedding blaxxun3D” on page 113 for details on the applet 
parameters. Please also note, that you must specify the mayscript tag for the 
applet to allow external script calls. 

Supported JS calls 

The following calls are available for interfacing blaxxun3D via Javascript: 


setNodeField (nodename , sets a value to the desired field in the 

fieldname, value) specified node. 

nodename is handled as string and 
must be exactly the same string as 
specified as DEF name in the VRML 
file 

fieldname is handled as String and 
must be exactly the same string as 
the appropriate field of the node. 

value is handled as String and auto¬ 
matically converted to the correct 
VRML data type. 
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getNodeField(nodename, 
fieldname) 


addFieldScriptObserver 
(nodename, fieldname, 
callbackFunction) 


reads the value of an eventOut of the 
specified node. 

nodename is handled as string and 
must be exactly the same string as 
specified as DEF name in the VRML 
file 

fieldname is handled as String and 
must be exactly the same string as 
the appropriate field of the node, 
registers an event observer which is 
called whenever an event at the 
desired field of the specified node 
occures. 

nodename is handled as string and 
must be exactly the same string as 
specified as DEF name in the VRML 
file 

fieldname is handled as String and 
must be exactly the same string as 
the appropriate field of the node. 

callbackFunftion is the name of the 
Javascript function that is called 
when the event occurs. The event¬ 
receiving javascript method must be 
implemented this way: 


function javascriptmethod 
(type,nodename,fie1dname) 

where type is the event type, node¬ 
name is the name of the node that 
launched this event, and fieldname 
is the name of the field that launched 
this event. 

Note that you must add a javascript 
browser observer after the applet 
has been loaded. 
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removeFieldScriptObserver 

removes an observer from a field. 

(nodename, fieldname , 
callbackFunction) 

nodename is handled as string and 
must be exactly the same string as 
specified as DEF name in the VRML 
file 

fieldname is handled as String and 
must be exactly the same string as 
the appropriate field of the node. 

addBrowserScriptObserver 
(String scriptmethod) 

callbackFunftion is the name of the 
Javascript function that is called 
when the event occurs. 

Add a javascript observer for 
browser events. Any changes in the 
browser will be sent to this observer. 
The order in which observers are 
called is not guarenteed. An 
observer can only be registered 
once. This means that multiple reg¬ 
istrations are ignored. But it is possi¬ 
ble to add different observer for one 
browser. 

The javascript method should be 
done this way: function javascript- 
method (type,nodename,fieldname) 
where type - the event type 
nodename - the name of the node 
that launched this event (in case of a 
browser event it’s null) 
fieldname - the name of the field that 
launched this event (in case of a 
browser event it’s null) 

removeBrowserScriptOb¬ 
server 

(java.lang.String script- 
method) 

also consider that you MUST add a 
javascript BrowserObserer after the 
applet has been loaded. 

Remove a javascript observer for 
browser events. 
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Supported observer events 

When using an event observer the following events can be observed 


Field Observer 

public static final int 

FIELD_CHANGED 

a field or eventOut has changed. 

Browser Observer 

public static final int 
INITIALIZED 

The browser has completed the ini¬ 
tial loading of the world. Event is 
generated just after the scene has 
been loaded and just before the first 
event has been sent 

public static final int 
SHUTDOWN 

received int value = 0 

The currently loaded world is about 
to be unloaded. Called just before 
the scene is about to be unloaded. If 
another world is to replace this, then 
an initialize event will be generated 
following this one. 

public static final int 
URL_ERROR 

received int value = 1 

An error occurred in loading X3D 
from a URL call, because of a pars¬ 
ing / file format error, connection 
error or other failure 

public static final int 
URL_LOADED 

received int value = 2 

a URL was loaded successfully, field 
is the children field of the group node 
containing the loaded nodes or 

NULL in case the world was loaded 
by an anchor. 

public static final int 
ANCHOR CLICKED 

received int value = 3 

an anchor has been clicked 


received int value = 5 
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public static final int The number of reserved identifier 
last_identifier numbers for event conditions. Any 

values above this are browser spe¬ 
cific messages. 

received int value = 100 


Examples 

Examplel illustrates the setting of values (e.g. switch node values or startTime/ 
stopTime) from HTML to VRML. 

Example2 demonstrates the use of the ScriptObserver. 

Accessing Javascript from VRML 

It is possible to access any Javascript-Function in HTML from a VRML file. Using 
the following call in an Anchor node accesses the specified function: 


"javascript:myJSFunction() 


If the specified function is declared in an HTML document in another frame, the 
target must be specified using the parameter field of the Anchor. See example 
code below for details: 

Example 1: Calling a JS-Function by an Anchor 

DEF anchor1 Anchor{ 

url"j avascript:externalFunction() ; " 
parameter["target=_self"] 
children[ 


} 


Java-EAI 


Using the Java-EAI you can write seperate Applets that connect to the browser 
applet in order to control the 3d scene. Using Java may be much more suiteable 
when handling complex mathematical operations. Also the powerful Java API 
serves you with more functionality which gives you more control over the 3d pro¬ 
cesses compared with Javascript. You can for example dynamically create and 
delete 3d content using createX3DFrom~ calls which are not supported in Java¬ 
script. 

The full documentation of the Java API can be found at here. 


Please read also the “blaxxun X3D-Proposal” on page 195. 
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VRML97 Compatibility 


blaxxun Contact 3D supports VRML97. 

Contact 4.41 and below additonally support VRML 1.0 for backward compatibil¬ 
ity. Contact 5.0 does not support VRML1.0 


Caching 


In addition to HTML browser caching, blaxxun Contact3D supports a mechanism 
to cache VRML files and referenced media such as textures, sounds and movies 
on the local hard disk. Caching is controlled by the "Caching" and "Cache Set¬ 
tings" tabs in the Preferences dialog of blaxxun Contact (press Ctrl-F9). 

With the default Setting "Verify once per session", VRML files are retrieved using 
the HTML browsers functions. All files retrieved by Contact3D are written to the 
cache with the server timestamp. The next time the files are needed, the current 
VRML server file date is compared to the VRML cache file timestamp. If dates 
are identical, all referenced media files are read directly from the cache without 
further HTTP requests. This greatly improves loading performance if the world is 
visited frequently. 

In Contact 4.3 the URLs of Inline and EXTERNPROTOs are verified for change. 
Files considered corrupt like truncated WAV files, images or VRML with unex¬ 
pected syntax errors (often caused by interrupted downloads) are deleted from 
the cache. 

If an author modifies an individual texture, the referring VRML file should also be 
touched in order to be refreshed by Contact3D. Media placed in locations con¬ 
taining "/cgi-bin/" or 7no_cache/" in the URL are retrieved each time. 

The lastModified Date for an URL from the HTTP server is set as the creation 
time for the cache file, the modified date is the timestamp of last retrieval or 
cache storage. Applications can install VRML content directly to the Contact3D 
cache with the proper timestamps, or can add a directory to the list of read-only 
directories. The cache is automatically cleaned from time to time. 

In Contact 5.0 if the url contains 7_cached/" the resource is always taken from 
cache if existing. If an author needs to change the resoure, he must rename it 
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and adapt any references. Using Browser.setOption(’refreshTimeVTRUE’) the 
session refresh time can be set to the current time. 


Universal Media 

blaxxun Contact uses URNs (Uniform Resource Names) to reference media ele 
ments such as textures, sounds and objects according to a mechanism pro¬ 
posed by the Universal Media Group. Details of the proposal can be found 
here. The url needs to start with M um:web3d:media M 

Laurent Gauthier of the Universal Media Working Group provided incremental 
installation of Universial Media files with Contact 4.3 or higher. The download 
location can be edited in the Contact3ds cache settings. Media parts of UM 
residing on 4 Universal Media mirror sites are incrementally installed. 

Contact 4.41 or higher supports the URN in url coding too, the url needs to con 
tain 7urn:web3d:media/ M and reside on one of the official UM mirrors. 


Tips, Known Problems and Workarounds 

• During scene loading in Internet Explorer, there is no feedback from the 
Internet Explorer logo animation to indicate download activity. 

• If scenes appear too dark, the headlight can be enabled in the Popup 
Menu. 

• The MovieTexture supports animated GIFs (GIF 89a) and static image 
formats. If the Microsoft DirectMedia runtime is installed, other video for 
mats are supported. The sound of movies cannot yet be played via a 
sound node; it is currently played directly using DirectSound. 

• There are limitations in the implementation of VRML geometry sensors. 

• Some rendering features can currently not be provided in the Direct3D 
version; see the Notes in the “Direct3D Issues” on page 174. 

• The Microsoft Direct3D ramp emulation computes lighting with a very sim 
plified model. Ambient lighting and the specular color are not additive. 

Workarounds: 

- Black faces due to missing ambient lighting: add a directional light 
source. 

- Completely bright faces when lighted: set the specularColor to the de¬ 
fault value 0 0 0 
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- Incorrect specular color: specify specularColor very bright, e.g. 0.9 0.9 
0.9 

- Insufficient display quality of lighted texture: use unlit textures Appear¬ 
ance {texture ImageTexture {..}} 

• IndexedLineSets and PointSets are currently not selectable by Anchors 
or geometry sensors. 

• The triangulation algorithm in the Direct3D version if no OpenGL libarary 
is installed, occasionally makes some small mistakes in rendering fonts. 

• blaxxun Contact3D registers the Web Browser for the file extensions wrl, 
wrz, vrml. It's recommended that gzipped VRML files be stored with the 
extension “wrl” on a website. 

• For compatibility with existing multi-user worlds: if the VRML scene graph 
contains no light at the root level, Contact 3D makes all DirectionalLights 
in the initial scene graph global. Authors should ensure that avatars in¬ 
serted by blaxxun Contact also get lighted. 

• In some worlds the visible depth range needs to be adapted in order to 
resolve z-buffer resolution problems. Depending on the scene, the 
workaround is to add bboxSize bboxCenter fields to some Inline / Group 
nodes, to specify a visibilityLimit in the Navigationlnfo node or, if the 
scene flickers, to increase the first number in the avatarSize field of the 
Navigationlnfo. 

• A Viewpoint node removed from the scene graph, but still referenced by 
script node fields, will still appear in the Viewpoint popup menu. 
Workaround is to set the description to an empty string in order to make 
the viewpoint disappear from the menu. The same applies to viewpoints 
switched off using a Switch node. 

• Viewpoint binding from VRML will do a Viewpoint animation, similar to the 
menu function. 

• Scripts inside PROTOs need to set the directOuput TRUE flag, if nodes 
are modified via direct access, or browser calls like addRoute, deleteR- 
oute, createVrmIFromUrl. All nodes of the PROTO definition that the 
script is going to modify need to be listed directly (i.e. not as children of a 
Group node) in some SFNode / MFNode field of the script. Otherwise the 
node may be shared between different instances of the PROTO, resulting 
in unexpected behavior. 

• Different versions of Windows 95 seem to show different scheduling and 
multi-tasking behavior; blaxxun Contact3D will run better concurrently 
with other applications using the later Windows 95 versions. The frame 
rate is currently limited to a maximum of 20 updates per second in Win¬ 
dows 95. To grab more CPU cycles in order to run at a higher frame rate, 
activate the "run full speed" setting in the Settings->Preferences->Gener- 
al dialog (Ctrl-F9). 
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Windows NT does not have this limitation. Pressing the F7 key displays 
the frame rate; the first number is the actual frame rate averaged over 
several frames, the second number is the time needed for the last scene 
redraw. 


Known Bugs 


• The initialize function of Scripts in EXTERNPROTO's are not always 
called. A workaround is to place the Script in the "traversed" scene graph 
part of the Proto scene graph. 

• Sounds are not not automatically disabled if switched off the scene graph 
using a Switch node. The workaround is to use the enable field of sounds 
to turn off sounds. 

• Only IndexedFaceSet supports continous crease angle values, other 
nodes only binary 0 or 3.14 values. 

• Circular node references are resulting in memory leaks. Workarounds are 
to null SFNode values in the shutdown() function of a script or better re- 
structering the nodes to avoid loops. 

• "Excessive" proto structures with many fields are currently consuming to 
much memory. 

• There are limitations in ElevationGrid handling. 


Direct3D Issues 

blaxxun Contact 3D is optimized for the Microsoft Direct3D immediate mode ren¬ 
dering engine. Support includes DirectX 3, DirectX 5, DirectX 6,DirectSound, 
Direct3D Sound and DirectShow. Using low-cost Direct3D accelerator cards, 
exceptional VRML 3D speed and quality could be achieved. TheDirectX inter¬ 
faces are very close to the hardware, graphics boards and drivers are quickly 
evolving. 

Windows 98 comes with DirectX 5 pre-installed. 

Windows 2000 comes with Direct X 7 installed, but requires special new hard¬ 
ware drivers from board vendors 

Windows NT 4 with Service Pack 3 installed supports DirectX 3 (but without 
hardware driver support). 

Windows NT 4 without Service Pack 3 does not support Direct3D, only OpenGL. 
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In general, OpenGL software rendering runs faster on Windows NT than on Win¬ 
dows 95/98. There are different Direct3D drivers available; features may vary 
and some drivers may not supply all rendering capabilities described in the 
VRML lighting model. 

Hardware 

Direct3D hardware is installed if there is a checkmark next to the "Hardware" en¬ 
try in the popup menu, blaxxun Contact3D will also prompt for the use of a hard¬ 
ware device. If hardware works with your current desktop and graphics card 
configuration, it can be made the default setting by selecting it in the Direct3D 
tab of the Preferences dialog: press Ctrl-F9 or right-click in the 3D window, select 
Settings, then Preferences and, in the Direct3D tab, select "Hardware" in the 
Direct3D Driver drop-down box. 

For a 16-bit desktop setting, enabling the Dither option in the Direct3D tab will 
usually improve display quality; for maximum speed, the "High speed" setting in 
the General tab needs to be enabled. 

Most accelerators today support 3D only in a 16-bit (32000 or 65000) color set¬ 
ting. With this setting, the Windows dialog Settings->Control Panel->Display- 
>Settings->Color palette would display "High Color (16-Bit)." 

Mip-mapping can be activated by checking the "Mip Mapping" option in the 
Direct3D tab; after a resize or a reload, the hardware will automatically switch 
between different scaled-down versions of a texture (the mip-levels), making tex¬ 
tures flicker less. 

Trilinear mip-mapping can be enabled by selecting the settings "Smooth Tex¬ 
tures" and "Mip Mapping". For a given pixel, the hardware first interpolates two 
color values in each of the two selected mip-levels and then interpolates 
between the two. 

Newer graphics boards (e.g. those based on the Riva TNT chipset) support sort- 
independent scene antialiasing. This can increase visual quality along sharp 
edges of geometry and text. 

Specific Direct3D Hardware Driver Limitations 

Some hardware drivers have limitations depending on type of chip set or version 
of the driver. In general, color per face and geometry shapes with more then 
1024 vertices are getting inefficient, especially if animated. Because in the cur¬ 
rent implementation information is cached at the geometry level. It is currently 
not possible to animate a given shape from an unlit to a lit state. 

The following settings make a shape unlit: 

• appearance in Shape is NULL 

• material in Appearance is NULL 
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• geometry node has the colorPerVertex attribute and a Color node. 

Tips for Using Direct3D Hardware Acceleration 

Successful use of Direct3D hardware acceleration is directly related to the 
graphics card's memory, current screen mode, and size of the 3D window. Using 
low-resolution screen modes like 640*480*32K colors leaves more memory 
available for 3D buffers and textures. If Direct3D can't use the hardware becau- 
seof too high memory requirements, blaxxun Contact3D falls back to the 
Direct3D ramp software driver. (Typical Contact3D error messages: "Create Sur¬ 
face for Z-Buffer failed" or "Create Surface for Window BackBuffer failed") 

Recommended display settings for hardware use (Hardware == Direct3D HAL 
Driver): 

• Graphics board with 4 MB video memory: Set desktop to 800*600, 32,000 
colors, use one 3D window only. 

• Graphics board with 8 MB or more video memory: desktop can be set to 
higher resolutions than 800*600 or multiple 3D windows can be opened. 

As a rule of thumb, the required graphics board memory can be computed as 

(pixel width of desktop * pixel height of desktop * 2) 

+ 

(pixel width of 3D window * pixel height of 3D window * 2) *2 
+ 

size of used textures in VRML scene (for non AGP boards) 

(2 Bytes per pixel for a 16 bit color setting, a window backbuffer and a z-buffer 
need to be allocated) 

If Direct3D hardware runs out of texture memory for storing all the textures, 
blaxxun Contact3D automatically reduces texture bit formats and scales down 
textures, resulting in a "blockier" appearance of the images. More elegant solu¬ 
tions include switching to software rendering for a scene, releasing some mem¬ 
ory on the graphics board by using a smaller window or lower desktop resolution, 
or upgrading to a graphics board with more memory (8 MB, 16 MB) or an AGP- 
based system. 

Another issue is the number of different texture pixel formats a board supports 
and whether it only supports square textures. For example, for a board support¬ 
ing only square texture formats, Contact3D scales up non-square textures. With 
a board that does not support palette 8 textures, Contact3D needs to expand GIF 
textures to a RGB format. Detailed information of a board's capabilities is pro¬ 
vided by the DXView program part of the DirectX SDK. 
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the Direct3D settings tab. This number should be much larger then the memory 
on the graphics board, otherwise the AGP support is not properly set up. On 
older Win95 systems, AGP support can be installed using the usbsup Windows 
update. 

The default Direct3D start configuration can be specified in the "Settings->Pref- 
erences" dialog. Direct3D drivers evolve quickly, so it’s a good idea to check the 
board vendor’s website for graphics driver updates. Information about the 
installed driver version is available in the Windows Control Panel, Icon DirectX - 
> DirectDraw > Installed Drivers. 

Running software modes on hardware is slow, and requires you to turn off the 
option "Use Video Memory" in the Direct3D settings tab of Contact 3D.Rendering 
is then performed in the PC’s main memory. 

Preliminary support for Direct3D full-screen rendering is available. Ideally the 
VRML world should be displayed full-screen in the HTML browser with menu, 
tool and status bars disabled. Pressing F5 will toggle between full-screen and 
window mode. The full-screen display mode can be selected from the Direct3D 
Fullscreen Mode drop-down box in the Direct3D settings tab; the default is 
640x480x16. If there are display problems, try downloading an updated DirectX 
driver from the graphics board vendor’s website. The drivers shipped with graph¬ 
ics boards are often out of date. 

On systems equipped with an MMX CPU, the DirectX 3 "RGB Emulation Driver" 
provides MMX-specific acceleration. With DirectX 5 there is a separate "MMX 
speed" Direct3D driver. With DirectX 6 the "RGB Emulation Driver" automatically 
uses MMX specific codepaths. 

Secondary Direct3D boards (3Dfx Voodoo and Voodoo2 etc.) which can only 
render full-screen and not inside a window are currently not supported. 


Software Drivers 

The speed of software rendering depends on the size of the rendering window 
and the CPU speed. 

Microsoft Direct3D Ramp Emulation Driver (Setting "High Speed") 

This driver is optimized for speed, not for quality. 

Limitations: 

• No color per vertex support. (Provide a fallback Material in the Appear¬ 
ance node) 

• Because there is no support for color per vertex, the color gradient form 
of the Background node is ignored. 
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• No colored light sources 

• Simplified light model (Problems with emissiveColor and specularColor) 

• No ambient lighting 

• No fog support 

• Internally supports only 8-bit palette Textures, Contact 3D has to reduce 
all textures 

• No RGBA textures, no texture clamping; RGBA textures are dithered to a 
binary transparency. 

• Pill & Contact Software lighting not supported 

Microsoft Direct3D RGB Emulation Driver (Setting "High Speed") 

The Driver is optimized for quality not for speed; beginning with DirectX 6, there 

are many quality improvements and code paths for different CPU types. 

Microsoft Direct3D MMX-Emulation driver (Setting "MMX Speed") 

Limitation: 

• internally supports only 8-Bit palette Textures, Contact 3D needs to re¬ 
duce all textures. 

• Enabling the Direct3D rendering options Dither, Mip Mapping, Smooth 
Textures and Anti Alias will have a negative impact on rendering speed of 
software drivers. 

Limitations for all other Microsoft Direct3D Drivers 

• Color per vertex supported, but shapes are treated as unlit. 

• Texture clamping (repeats FALSE) supported beginning with DirectX 5 

• Only linear fog supported 

• Mixing a material transparency with a texture works in some Direct3D 
drivers. 
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Elevator-Proto 


The blaxxun Platform is delivered with an elevator proto. The elevator proto is 
the technical implementation of an elevator that can be integrated into any VRML 
world. Without special programming efforts, elevator functionality can be added 
to a scene. However, this proto does have a restriction: selection of the desired 
floor must take place outside of the elevator doors (if present). For other use, the 
proto would have to be modified. 

The proto provides the following functionality: 

• The user selects the desired floor using a button. 

• On entering the elevator, the user is automatically animated to a position 
that is either specified by a viewpoint or generated automatically. 

• The elevator simulation starts; the elevator platform and the user are 
moved to a new position (floor). 

The following description is limited to integration of the proto and possible con¬ 
figurations. 

The proto should be integrated into the VRML world as an externproto, or the 
source code simply inserted via copy & paste. 

Referencing as externproto 

EXTERNPROTO Elevator[ 

field MFInt32 targetFloors #set order of floors according 


#to the sequence of floor 

#selection buttons 

#NOTE: use 1 for ground floor 


field MFVec3f floorPos 


#set positions of floor ground 
#in absolute world coordinates 


exposedField SFNode vplnside #optional: if defined in the 


#world, set a viewpoint for use 
#inside the elevator 


field SFNode platform 


#set geometry to use as lift 
#floor 
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field MFNode triggers 


#set touchsensors to trigger 
#the elevator 


field SFVec3f proxySize 


field SFTime driveTime 


#optional: set size for proxy 
#inside the elevator 
#if set to 0 0 0 the user gets 
#animated into the elevator by 
#clicking the button 

#optional: set time for 
#elevator animation 


field SFBool autostart #optional: if set to FALSE the 

#elevator will not start 
#automatically and will wait 
#for an eventln startAni 


field SFFloat automaticStartDelay #optional: time after which 

#the elevator will start to 
#run automatically, only 
#relevant in combination 
#with autostart 


eventOut SFBool viewpointBound 


eventOut SFTime bindTime 


eventOut SFTime aniOverTime 


eventOut SFBool aniOver 


eventln SFTime startAni 


field SFBool rotateUserOnEntry 


#sends boolean event if the 
#elevator viewpoint is bound 

#sends SFTime event, when the 
#elevator viewpoint is bound 

#sends SFTime event, when the 
#elevator animation is over 

#sends SFBool (value = FALSE 
#!!!) event, when the elevator 
#animation is over; 

#optional: SFTime event to 
#start elevator ani manually 

#rotates the user 180 degrees 
#to make him look in the 
#opposite direction to his 
#orientation on entry 


field SFBool rotateBackUserOnExit #when rotated this setting 

#rotates him back on exit 
#either to the given 
#exitOrientation or to the 
#orientation he had when 
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#clicking the button 
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field MFRotation exitOrientations #optional: set orientations 


#the viewer should look at 
#when leaving the elevator. 
#If set, there must be one 
#orientation for each floor 
#otherwise the setting is 
#ignored 


]"elevator_proto.wri" 

Instancing 

If the proto is referenced as an externproto as demonstrated above, it can be in¬ 
stanced as in the following example. 

DEF lift Elevator{ 

targetFloors[2, 3, 1, 3, 1, 2] 
floorPos [000, 030, 060] 
vplnside USE KameraOl 
platform USE platform 

triggers [USE TS1, USE TS2, USE TS3, USE TS4, USE TS5, USE TS6] 
proxySize 555 
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Proto fields and default values 

The proto can be configured to the needs of the scene by assigning appropriate 
values to its fields. These fields are described in the table below. For the first four 
fields, values must be explicitly set; for others it is optional. 

targetFloors In this field, the correct sequence of 

destination floors must be given in 
terms of each floor’s buttons. For 
example, for an elevator that is only 
supposed to move between the 
ground floor and second floor, at the 
ground floor entrance there would 
be a button for the second floor, and 
at the second floor entrance there 
would be a button for the ground 
floor. Since the ground floor is desig¬ 
nated 1 in the proto, the field would 
look like this: 

targetFloors[2,1] 

For three floors, there would be but¬ 
tons for 2 and 3 on the ground floor, 
for 1 and 3 on the second floor, and 
for 1 and 2 on the third floor. The 
field would then be set as follows: 

targetFloors [2 , 3, 1, 3, 1, 

2 ] 

The proper order is vitally important! 

This field receives the positions for 
the platform (elevator floor) in abso¬ 
lute world coordinates. 

The platform to be moved (transform 
node of the respective geometry) 
must be passed to this field. 

The appropriate TouchSensors 
used for floor selection (from bottom 
to top corresponding to the button 
order) must be entered into this field 
in the correct order. 


floorPos 


platform 


triggers 


182 






Useful Application Modules 

vplnside 

Using this field, a viewpoint defined 
in the world can be passed to the 
proto. 

If this field is set, the user will take on 
the position and orientation defined 
for the viewpoint. 

proxySize 

If this field is not set, the user will be 
positioned at the middle of the eleva¬ 
tor with an orientation 180 degrees 
from that when the floor selection 
button was clicked. 

The proto contains a Proximity- 
Sensor that determines whether 
the user has entered the elevator. 

The field proxySize should be 
used to adjust the sensor to the 
actual dimensions of the elevator. 

If this field is set to 0, 0, 0 then the 
ProximitySensor used for mov¬ 
ing the user to the elevator will be 
deactivated and the user will be 
moved immediately on clicking the 
button. 

driveTime 

Default value is 3, 3, 3 

This field can be used to specify the 
duration in seconds of the elevator 
animation. 

autostart 

Default value: 3 

If autostart is set to TRUE 
(default), the elevator animation will 
start automatically as soon as the 
user occupies the elevator and a 
specified waiting interval expires. 


If autostart is set to FALSE, the 
proto waits for an event to start the 
animation. 
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automaticStartDelay Specifies the time (in seconds) that 

the elevator waits after the user 
enters, before the animation starts. 

Default value: 1.5 

rotateUserOnEntry This field only has an effect if the no 

viewpoint to be animated is passed 
to the proto, so that the proto’s 
default viewpoint is used. If this field 
is set to TRUE, then the user will be 
rotated 180° before the elevator 
moves. This rotation - if no orienta¬ 
tion for the user is specified with the 
exitOrientations field - is rela¬ 
tive to the orientation that the user 
had when he clicked on the floor 
selection button. But if orientations 
are specified with the exitOrien¬ 
tations field, then the orientation 
at the time of the click will be ignored 
and the user will be rotated 180° 
from the respective target orienta¬ 
tion. 

Default value: TRUE 

rotateBackUserOnExit This field is the opposite of the previ¬ 

ous field and therefore only has an 
effect if rotateUserOnEntry is 
set to TRUE. 

If this field is set to TRUE, then the 
user will be returned to the target ori¬ 
entation for the current floor on leav¬ 
ing the elevator (exitOrienta¬ 
tions) or, if no target orientations 
are set, to the orientation he had 
when he selected the destination 
floor. 


Default value: FALSE 
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exitOrientations 

In this field, desired orientations for 
each floor can be set; before users 
leave the elevator, they will assume 
the orientation set for the current 
floor. This field only has an effect if 
the proto’s default viewpoint is used. 

If the number of set orientations 
doesn’t match the number of floors, 
this setting is ignored. 

Default value: [] 

Events 


viewpointBound 

Sends an sfbooI event when the 
user has assumed the elevator posi¬ 
tion. Can be used, for example, to 
trigger a “close door” animation. 

bindTime 

Sends an SFTime event when the 
user has assumed the elevator posi¬ 
tion. Can be used, for example, to 
trigger a “close door” animation. 

aniOverTime 

Sends an SFTime event when the 
elevator animation is finished. Can 
be used, for example, to trigger an 
“open door” animation. 

aniOver 

Sends an sfbooI event when the 
elevator animation is finished. Can 
be used, for example, to trigger an 
“open door” animation. 

startAni 

Triggers an Event in SFTime for 
manual start of the elevator anima¬ 
tion. Only makes sense if 
autostart is set to FALSE. 


Release Notes 

Note: The elevator platform to be animated, which is passed to the proto in the 
platform field, must be included in the scene graph at the top level. That 
means it can’t be part of a group or the hierarchically subordinate child of another 
geometry since the proto directly accesses the position values of this platform, 
and a different scene graph arrangement would lead to malfunctions. 


If the user is in third-person mode when he enters the elevator, that mode will be 
turned off during the elevator ride so that the camera can’t end up behind the ele¬ 
vator walls. On leaving the elevator, third-person mode will be reactivated, as 
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long as the elevator proxy hasn’t been deactivated by the proxysize o o o 
setting. 

Usage Examples 

The elevator proto is used in two different ways in the sample worlds of the Vir¬ 
tual Worlds Platform. 

Shop 

A viewpoint defined in the shop is passed to the proto as the viewpoint to be used 
during an elevator ride. The autostart field is set to FALSE here, so the ele¬ 
vator ride doesn’t begin automatically as soon as the user enters the elevator, 
but manually via a script in the shop world. The reason is that the elevator ani¬ 
mation isn’t supposed to start until the elevator doors are shut. This condition is 
monitored by the external script and, as soon as the door animation is complet¬ 
ed, the elevator ride will be started via the elevator proto’s startAni event. 

DEF lift Elevator{ 
targetFloors[2, 1] 

floorPos [-10.024 0 1.271, -10.024 7.108 1.271] 

autostart FALSE 
platform USE elev_floor 

triggers [USE TouchSensor_elev_butl-SENSOR, USE 
TouchSensor_elev_but2-SENSOR] 
proxySize 10 20 10 
vplnside USE cam_elevator 

} 


Community Center 

In the Community Center, the proto’s default viewpoint is used by not setting the 
vplnside field. This approach presents itself because, in this case, elevator en¬ 
try and exit take place on different sides of the elevator. The default viewpoint is 
configured by explicitly specifying user orientations in the exitorientations 
field. The rotateUserOnEntry field is set to FALSE, with the result that the 
user is not rotated by 180 degrees during the animation in the elevator but is ro¬ 
tated directly into the orientation that is to be taken on exit from the elevator. 

Since the proxysize field has the values 0 0 0 here, the proto’s proximity sen¬ 
sor is deactivated and the user is animated directly into the elevator on clicking 
the destination floor’s button. In contrast to the shop, the elevator animation 
begins automatically in this case; the autostart field is set to TRUE, the 
default value. 

DEF liftl Elevator{ 
targetFloors[2, 1] 

floorPos [16.69 -0.3002 12.38, 16.69 7.6 12.38, ] 

platform USE platforml 

triggers[USE TS1 upl, USE TS1 downl] 
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proxySize 000 
driveTime 3 
rotateUserOnEntry FALSE 

exitOrientations[0 1 0 -1.56, 010 1.56] 

} 


Random Viewpoint 


When a user loads a VRML world, he is automatically positioned at the start 
viewpoint. If he doesn’t move from this position, or if another user enters the 3D 
world at the same time, then the users’ avatars may get stuck together since they 
have been inserted into the world at the same place. This can render some users 
temporarily immobile, which can be a cause of frustration, especially for less 
experienced users. 

The Randomviewpoint proto, which is distributed with the blaxxun Platform, 
solves this problem by moving the start viewpoint randomly within a specified 
radius. The proto can be integrated into the VRML world as an externproto. 


EXTERNPROTO Randomviewpoint[ 
field SFNode entryCam 

field SFFloat minDistance 


field SFFloat maxDistance 
]["random_viewpoint.wri",] 


#tell the Proto which Viewpoint 
#should be modified 

#sets the minimum distance from 
#the original Viewpoint position 

#sets the maximum distance from 
#the original Viewpoint position 


If the proto is referenced as shown above, it can be instanced as follows: 

DEF randomizer Randomviewpoint{ 
entryCam USE Start 
minDistance .5 
maxDistance 3 

} 

We advise instancing the proto only after the viewpoints in the VRML file. This 
makes it possible to pass the start viewpoint that is to be manipulated to the proto 
via use. The proto will then write its changes directly to the viewpoint. 


blaxxun 
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The proto can be configured to the requirements of the scene using the fields 
described in the table below. 


Field 

entryCam 


minDistance 


maxDistance 


Description 

This field must be passed to the 
viewpoint to be manipulated via 
USE. If this isn’t done, it’s impossible 
to randomly calculate the start view¬ 
point. 

This field specifies the minimum dis¬ 
tance from the original position. 
Default value is 0. 

This field specifies the maximum 
distance from the original position. 
Default value is 3. 


The proto works such that the random viewpoint is inserted somewhere within a 
ring centered on the viewpoint defined in the VRML file; the ring’s inner diameter 
is given by minDistance and its outer diameter by maxDistance. 



Fig. 7: Mode of action of the Proto 

Note: The orientation of the start viewpoint will also be changed, but this can’t 
be controlled by field settings. Possible values are between -0.25 and 0.25 radi¬ 
ans from the original orientation. 

The Randomviewpoint proto is used in some of the Virtual Worlds Platform’s 
sample worlds. These include shop.wrl, commcenter.wri and hall.wrl. Since 
these worlds are more frequently visited, use of the proto helps to avoid unnec¬ 
essary collisions between avatars. 








MediaControl-Proto 
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The MediaControl-Proto manages a list of given video or audio files and starts/ 
stops the selected file. It is possible to browse through the list of media files 
whereupon the title of the media file is shown. This may be a given text node 
which is modified or an appropriate texture is loaded. 

The shape on which the video is shown sgould be mapped with an ImageTex- 
ture. The proto swaps this texture after pressing ’play’ when used with streamed 
content with a ’please wait’ texture and as soon as the content is available with 
the desired video. When pressing ’stop’, the original texture is shown again. 

It is important to note that by using this proto the content author doesn’t have to 
care about the manual integration of MovieTexture or similar nodes. This is all 
managed by the proto. 

The proto should be integrated as an Externproto. 

Referencing as externproto 

EXTERNPROTO MediaControl[ 
eventln SFTime forwardTouched 
eventIn SFTime backwardTouched 
eventln SFTime playTouched 
eventln SFTime stopTouched 
field MFString loadTex 
field MFString mediaNames 
field MFString mediaFiles 
field SFNode displayText 
field SFNode videoShape 
field SFNode titleTextureNode 
field MFString titleTextureFiles 
field SFBool showLoadingTexture 
field SFBool showVideo 

/common/Media_control.wrl" 

Instancing 

If the proto is referenced as an externproto as demonstrated above, it can be in¬ 
stanced as in the following example. 


DEF control MediaControl{ 
mediaNames[ 

"filml", "film2", 

] 
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mediaFiles[ 

"http://www.blaxxun.de/company_video.ram' 
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"rtsp://someHost/someFolder/someFile" 

] 

videoShape USE bigVideoShape 
titleTextureNode USE titleTexture 
titleTextureFiles["f1.jpg", "f2.jpg", ] 

loadTex /vrmlimages/loading.jpg" 

} 


190 


Proto fields and default values 

The proto can be configured to the needs of the scene by assigning appropriate 
values to its fields. These fields are described in the table below 


forwardTouched 


backwardTouched 


playTouched 

stopTouched 

loadTex 


mediaNames 


mediaFiles 

displayText 

videoShape 


An application may provide a button 
to browse forward through the media 
list. A Rout needs to be set from the 
appropriate TouchSensor to this 
eventln 

An application may provide a button 
to browse backward through the 
media list. A Rout needs to be set 
from the appropriate TouchSensor 
to this eventln 

eventln for starting the media clip 
eventln for stopping the media clip 
optional: 

image texture which is shown while 
the media is loaded after ’play’ was 
pressed 
optional: 

titles of the media clips which may 
be shown in a given Text node, 
list of URLs of the media files 
Text node which shows the defined 
media titles 

shape, on which the video clip is pro¬ 
jected 


Important notice: Even if audio clips 
will be played a shape must be 
defined. For the use of audio clips 
you may also see the field 
’showVideo’ 

titleTextureNode If the mediaNames shall be shown 

as textures an ImageTexture node 
must be defined in this field in order 
to change its texture when browsing. 







titleTextureFiles 


showLoadingTexture 


showVideo 
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list of ImageTexture files for the 
mediaNames 

flag which defines whether a loading 
texture is shown 
Default: TRUE 

flag, which defines whether video 
files shall be projected on the given 
Shape. 

If only audio clips will be used this 
field may be set to FALSE 
Default: TRUE 


SceneChange-Proto 

The blaxxun Platform 6 is delivered with a Proto that implements smooth scene 
changes, which are triggered on 3D actions, e.g. click on a door or walk through 
a gate. If the event for changing a community scene is triggered a HeadUpDis- 
play shows up. After that the call for loading a new scene is send. The new scene 
always loads with the HeadUp-Display being visible and fades it out after a given 
time. 

The Proto should be implemented as an EXTERNPROTO. In order to guarantee 
smooth changes it is necessary that the Proto is included in each VRML world. 
It is also necessary that every VRML file contains the Proto BlaxxunZone, which 
is described at “blaxxun SharedZone” on page 141 

To avoid that the target scene is shown for a short time before the HUD gets vis¬ 
ible and therefor the feeling of a smooth change gets lost it is recommended that 
the whole scene is encapsulated in a Group node and enclosed fom a Switch 
node. The Proto needs to know a reference of this switch node and turns on/off 
the world geometry automatically. 

Referencing as Extern proto 

EXTERNPROTO sceneChange [ 
field MFString strings 
field MFNode triggers 
field MFString parameters 
field SFNode switch 
field MFNode lightsInScene 
field SFBool unloadChat 
field SFString hudTexture 

] 
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/common/scene_change.wrl 
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Instancing 

If the proto is referenced as an externproto as demonstrated above, it can be in¬ 
stanced as in the following example. 

DEF changer sceneChange{ 
switch USE sceneSwitch 
triggers[USE AntiGProxy] 
strings[ 

"javascript:loadPlace(\"0\" / \"0000000000000022\",\"3dchatl 
#KameraChat\")", 

] 

parameters["target=action", ""] 

lightsInScene [ USE lightOl, USE light02,] 

} 


Proto fields and default values 

The proto can be configured to the needs of the scene by assigning appropriate 

values to its fields. These fields are described in the table below 

switch this field holds a reference on the 

Switch node, that should capsulate 
the scene. The reference should be 
overgiven via USE. It is necessary 
that the Instance of the Proto is set 
out of the switch node and in the 
code below it! 

If the scene is not capsulated by a 
switch, it is possible that the main 
scene is visible before the HUD is 
drawn and therefor the feeling of a 
smooth change is lost. 

triggers this field hold references to the sen¬ 

sors that may trigger the scene 
change (TouchSensor or Proximtiy- 
Sensor) 

strings this field holds the strings, which get 

used by the Proto in a Browser.loa- 
dURL call. In a community context 
these strings should always look 
like: 

“javascript:loadPlace(\”0\”, placelD, 
placeName)” 

It is also possible to refer to the 
desired VRML files directly in a ’non- 
community’-context. 






parameters 


lightsInScene 


hudTexture 

hudColor 
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this field contains the parameters for 
the Browser.loadURL function. Gen¬ 
erally this is the target frame in which 
the function is called, that performs 
the scene change. In a standard 
blaxxun community solution this 
frame is called ’action’, which is why 
the parameters is usually set to 
“target=action” 

if the scene is lightened using lights, 
references to these light nodes 
ought to be set here. The reason for 
that is the influence that these lights 
may have on the HUD. If references 
are set, the proto will turn off the 
lights and turn on the headlight. 
Doing this is the only possibility to 
make sure that the HUD is lightened 
identically between two different 
scenes. The new scene will be 
loaded with headlight on and will 
turn on their lights when the HUD 
fades out. 

image texture file for the HUD 
diffuseColor value for the HUD 
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blaxxun X3D-Proposal 


Introduction 

The Core X3D Specification is composed of a very lightweight set of 3D scene 
elements and programming interfaces upon which a wide variety of 3D applica¬ 
tions can be built. It is a strict subset of the VRML 97 specification and it is based 
on these concepts. Additionally Core X3D provides a powerful API for program¬ 
ming and extensibility. 


Goals 


• To provide a small enough set of requirements that a minimally compliant 
implementation can reasonably deliver the viewer application along with 
the content. 

• Compatibility with the VRML 97 standard to allow usage of existing au¬ 
thoring tools and even some existing content. 

• To provide a specification that can be implemented by a large number of 
companies and individuals without requiring a prohibitively large invest¬ 
ment. 

• To provide a set of requirements that can be implemented on many differ¬ 
ent platforms. 

• To provide enough functionality that a minimally compliant implementa¬ 
tion will enable the most commonly required features of 3D content pro¬ 
ducers. 

• To provide extensibility into areas that are not specifically addressed by 
this specification. 

• To provide a foundation for higher level profiles, including VRML97 and 
MPEG-4 compatible profiles. 

Proposal 

The blaxxun Core X3D Proposal. 
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blaxxun Nurbs Proposal 
Overview 


This project is intended to test the feasibility of using NURBS geometry and 
NURBS interpolation as either possible extensions to or recommended practice 
for VRML97. Results, data sets and a sample implementation are presented 
here. This work, together with the node specification, will be presented to the 
VRML community and the Web3D consortium for further discussion. 

The key benefits from the use of NURBS surface primitives include: 

• Complex smooth surfaces can be described using a minimum set of 
paramters, resulting in a huge compression advantage compared to high¬ 
ly detailed triangular meshes. 

• Smooth shape animations can be done by changing only a few parame¬ 
ters. 

• Computer modeling programs are already based on NURBS. 

• NURBS are scalable to client 3D graphics and CPU performance. 

These features allow a new level of visual display and animation quality for Inter- 
net-delivered 3D graphics. 


News 


The NURBS Proposal is part of VRML 97 Amendment 1--Enhanced interopera¬ 
bility : 

http://www.web3d.org/technicalinfo/specifications/vrml97am1/fdam/ 

index.html 

http://martinreddy.net/vrml/vrml97am1/ 

Parallel Graphics Cortona implements NurbsSurface node. Notes: the tessela- 
tion stragegy is different and supports an extra quality curve for fine tuning, if the 
knot vector is empty Contact & Cortona are computing different default knot vec¬ 
tors. 

Evgeneys Demidov 3D Splines & Web tutorials and examples 
Interactive NurbsSurface control 


Tools support White Dune, Spazz3D 
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blaxxun NURBS Proposal 
NURBS in VRML (PDF) 

a paper presented at VRML2000 conference, Monterey 


Example Content 



Knight Nurbs by Lunatic Interactive: For best results, use the dynamic tessella¬ 
tion mode. 

Example of a NURBS Curve 

The boxes represent the ControlPoints of the curve, which define the shape of 
the curve. While a conventional primitive is defined by a large amount of points 
on the curve itself, the NurbsCurve needs only the small amount of Con¬ 
trolPoints and a few other parameters. 

Low download size 

• Duck stored as NURBS -11 KB 

• Duck stored as low-medium resolution IndexedFaceSet : 179 K - 

4374 triangles 

• Duck stored as medium-resolution IndexedFaceSet : 469 K - 11070 
triangles 

• Duck stored as high-resolution IndexedFaceSet : 2.2 M - 50598 trian¬ 
gles 


These samples demonstrate the space savings that can be attained by using 
NURBS to represent complex shapes. The files are not compressed. The 
IndexedFaceSet versions contain coordinate, texture coordinate and coordlndex 
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information, but not the better-quality normals computed directly from the 
NURBS surface. 

NURBS and animation 

Simple animations, performed by modifying a single control point from javascript: 

• Animated 2x2 surface 

• Animated 3x3 surface 

• Animated 4x4 surface 

• Flying Birds 

Comparison: animated controlPoints vs. Coordinatelnterpolator 

• NURBS version, controlPoints are animated 

• Standard version, coordinates of a mesh are animated 

Free Form Deformation 

• Venus 

NURBS deformation on coordinates of IndexedFaceSet The Shape is en¬ 
closed in a grid box, only the grid points are animated. 

• Sphere 

NURBS deformation on controlPoints of a NurbsSurface 

LOD - Level Of Detail 

LOD examples, use these to view the effects of different tessellation mode set¬ 
tings, especially the first example. Note the dynamic tessellation as you move 
close to the objects. 

• Colony City plaza crowded with flock of NURBS ducks - a dynamic 
tessellation stress test 

• LOD Test with Okupi Bouncer - a dynamic tessellation stress test with 
several instances of the same NURBS model, ordered by distance 

• 4 Ducks 

• 4 Ducks & a head 


Perfect Smoothness 

This demo should show you what NURBS can do in comparision to a polygon 
based model. Typically when you zoom in closer to a 3D object based on a poly¬ 
gon model, the models get edgy sooner or later. Since we're using NURBS (a 
mathematical description of the surface), not only the file size get's smaller, but 
also the acuraccy is better, because with each step you move closer to the object 
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the VRML Plugin can tessalate the surface again with a resolution that can’t be 
seen by the human eyes. 

With this method so called Level of Detail can easily be achieved, because there 
is only one model, that gets tessalated as much as necessary. In a polygon 
based 3D model one would have to have several 3D models for each level of 
detail you want to display. 

Zoom to the Knight Nurbs Avatar - By using 'PageUp'/’PageDown’ keys you 
can jump between the various Viewpoints. Pressing 'PageUp' 3 times, you can 
see that there is no difference, regardless how close you get to the Avatar. 

Oku pi Avatars 

The following avatars and bots have been created by okupi. 

• Avatarl 

• Avatar2 

• Avatar3 

• Avatar4 

• Bouncer 

• Podium 

Models 

The following models are 3ds max example sets and have been exported using 
the enhanced blaxxun exporter for 3ds max.The source code is headed by an 
EXTERNPROTO definition. In this PROTO an IndexLineSet model of the Nurb- 
sSurface is computed for compatibility with browsers that don’t support the 
blaxxun NURBS nodes. 

• Head 

• Another head 

• Perfume bottle 

• Stingray 

• Duck 

• Pumpkin 

TIP: If you want to see the wire frame model formed by the control vertices, deac¬ 
tivate the urn-field in the EXTERNPROTO definition: 

### "urn:inet:blaxxun.com:node:NurbsSurface" 


Thus you can also check what a model will look like in other browsers. Have a 
look at the Head shown as wire frame. 


199 





Related Documents - Download Control 


Acknowledgements 

Special thanks to Michael Vollmer and Dean Maori, Intel Corporation, for their 
ideas and support. 

Thomas Volk for implementation and ideas. 

Please send any feedback to support@blaxxun.com or directly to 
holger@blaxxun.com. 


Download Control 

Order of download 

Contact 3D fetches URL objects and EXTERNPROTO’s in the order encoun¬ 
tered during scene graph traversal, in the order top to bottom of file, depth first. 
Currently not needed objects, because not "visible" due to a Switch, LOD or Bsp- 
Tree node are only retrieved if they become part of the visible scene graph. 

Loading of textures in the appearance node of a shape may be delayed until the 
shapes geometry becomes visible. 

The BspTree or BspGroup node traverses child nodes closer to the viewer first. 
This means Inline parts closer to the viewer are loaded earlier than parts further 
away. BspTree Parts outside the visibilityLimit (the viewing pyramid) are not 
fetched. The drawback is that once a new section of the world becomes visible 
there is a pause due to the decoding of image texture from harddisk to video 
memory. The chapters “BSPTree” on page 54 and “BSPGroup” on page 56 pro¬ 
vide more information on these nodes. 

Due the above mentioned loading behaviour a LOD node displays the currently 
visible level as long as the requested level is loaded. 

Preloading media files 

In order to preload currently unneeded objects, ImageTexture / MovieTexture / 
AudioClip nodes can be directly specified as children of Groups. The ordering of 
the nodes with url controls the download sequencing of the assets. The Appear¬ 
ance / Sound node references the asset by USE. 

The following example source code illustrates the use: 

DEF mediaAssets Group{ 
children[ 

DEF imagel ImageTexture{ 
url"somelmageFile" 

} 

DEF videol MovieTexture{ 
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url"someMovieFile" 

} 


} 

Shape{ 

appearance Appearance{ 
texture USE imagel 

} 

geometry #someGeometry 

} 

Shape{ 

appearance Appearance{ 
texture USE videol 

} 

geometry #someGeometry 

} 

Note, that this is an extension to the VRML97 Spec. Other VRML Browsers may 
report problems with this. 

Another option to force the Browser to preload media files is the additional 
Browser method prefetch. Using this Browser method it is possible to instruct 
the Browser to load Imagaes, AudioClips or MovieTextures even if they are not 
currently visible. The following example source code illustrates the principle. 
Please also read the chapter “Browser object extensions” on page 32 on addi¬ 
tional browser methods and their parameters. 

Shape{ 

appearance Appearance{ 

DEF imagel ImageTexture{ 
url"somelmageFile" 

} 

} 

geometry Box{} 

} 

Script{ 

field MFNode theMedia[USE imagel] 
url"vrmlscript: 

function initialize() 

{ 

nodesLoaded = Browser.prefetch( theMedia ); 


} 
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Controlling resource loading 

A common request from content developers is to have more control over re¬ 
source loading notification and unloading capabilities. 

The inline node behaves as a group-node. As an extension it contains a children 
field. The children field is exposed to access the nodes of the inline. By observing 
children_changed a notification is sent, once an Inline node is loaded and pro¬ 
cessed. 

The additional eventOut SFBool isLoaded indicates loading success, TRUE is 
sent once the inline node is loaded, FALSE is sent if the inline nodes url couldn’t 
be retrieved or there was another problem with the data. In addition 
set_unload can be used to unload an Node from memory, however the appli¬ 
cation should normally use this ONLY if its sure that the node is currently not part 
of the visible node subsets (i.e. out of viewing frustrum, not in traversed scene 
graph etc.) 

Please see the the chapters “ImageTexture” on page 77, “Inline2” on page 80 
and “MovieTexture2” on page 93 for the complete node descriptions and imple¬ 
mentation notes. 

As an extension it is possible to assign an image to a MovieTexture. Doing this, 
it is possible to observe the duration_changed eventOut. As this event is sent 
as soon as the media file is loaded, this technique provides an additional down¬ 
load control. Observing the "last" asset in source code order gives a hint of the 
completion of the loading process of the VRML world. 


Generic Input Handling 
Introduction 

With a set of new nodes (proposed for the VRML200x standard) the world 
builder can handle device events from mouse, keyboard and Drag & Drop. With 
the help of these nodes and an extended Viewpoint control node a world builder 
can implement customized navigation and user interfaces. Find a introduction 
and a description of the nodes in our paper e A Generic User Interface Frame¬ 
work’. A basic node reference can also be found at “Node Extensions” on page 
51. The latest errata to the node definitions and the implementation status are 
documented here. Additionally some browser extensions are available to config¬ 
ure contact with a VRML-based Ul. 
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Simple Beamto Navigation 

Standard Navigation Modes implemented with the Camera node 
Examine an object 
A quake like navigation 


Concepts 


Driving the Camera 

The basic function of the Camera node is to drive the camera at a certain speed 
specified by two vectors. Oposed to a viewpoint animation collision detection is 
performed. Additional fields allow to implement examine and jumpTo modes. 

Intercepting User Input 

Various nodes handle user input, basic browser functions (navigation module 
and the VRML sensor handler) compete with the new nodes for the user input. 
E.g. a mouse drag is possibly handled by the VRML author with a MouseSensor, 
and/or a PlaneSensor or the navigation module. An event cascade model 
therefore ensures operability. Events are first routed to the raw input sensors 
(the new nodes). The eventsProcessed eventln then determines if the given 
events flow further down the event cascade. If the event was not stopped (can¬ 
celled) by setting eventsProcessed to true, the events flow to the VRML¬ 
sensor event handler and finally to the built in navigation module. Note that the 
order raw input sensors receive events is undefined (the list of sensors is not or¬ 
dered). Therefore if you cancel any event in a raw input sensor you cannot en¬ 
sure that other raw input sensors do/did not receive the event. However most 
applications need at most one raw input sensor. 

MouseSensor and KeySensor are sufficient in most cases, for complex applica¬ 
tions you should consider the DeviceSensor with its open architecture. In its 
basic configuration the DeviceSensor acts similar to the Mouse- and the Key- 
Sensor, but allows further filtering of the input and provides additional informa¬ 
tion about the device, e.g. a certain keyboard group. The DeviceSensor itself 
acts as a shell for the actual event captured in a dedicated Event node. It initial¬ 
izes the device with the given filter information or loads external device modules 
for advanced input devices. An external device gets a pointer to the event node 
which is eitherthe built in Event-node or an instance of a device specific event- 
PROTO node. 
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Node proposal - Extension nodes for customizable input handling and 
navigation 

Camera 

Camera { 


eventIn 

SFBool 

set bind 


eventIn 

SFVec3f 

xyz 


eventIn 

SFVec3f 

ypr 


eventIn 

SFVec2f 

yp 


eventIn 

SFVec3f 

moveTo 


eventIn 

SFVec3f 

orientTo 


eventIn 

SFVec3f 

examineCenter 


eventIn 

SFBool 

straighten 


exposedField 

SFTime 

duration 

0 

exposedField 

SFInt32 

examineRadius 

0 

exposedField 

SFVec3f 

offset 

0 0 0 

exposedField 

SFBool 

collide 

TRUE 

exposedField 

SFBool 

gravity 

TRUE 

field 

SFString 

description 

II II 

field 

SFVec3f 

upVector 

0 10 

eventOut 

SFRotation 

orientation 


eventOut 

SFVec3f 

position 


eventOut 

SFTime 

bindTime 


eventOut 

SFBool 

isBound 



} 


A detailed description of the fields and implementation notes can be found at 
“Camera” on page 57 in the Node Extensions section 


DeviceSensor 

The DeviceSensor node observes arbitrary input devices such as a six degrees- 
of-freedom mouse or a speech recognition system. The device data is wrapped 
in an Event node (already suitable for many possible event types). Special pur¬ 
pose devices may replace the default implementation with their own Event node, 
guaranteeing maximum flexibility for all possible input devices. 


DeviceSensor { 
exposedField 
exposedField 
exposedField 
eventOut 
eventOut 

} 


SFBool 

SFString 

SFString 

SFNode 

SFBool 


enabled TRUE 

device "<device> [<number>]" 

eventType "all" 

event 

isActive 


The device field specifies the hardware device observed by the node. An 
optional number decides which instance of the device - if more than one are 
present - is used. By setting 
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device = "JOYSTICK 2" 

all events generated by the second joystick are reported by the DeviceSensor. 

<device> ::= STANDARD | JOYSTICK | SPACEMOUSE | ... 

standard reports events from the key board, mouse and drag & drop to the 
DeviceSensor. Other eventTypes report the respective subset of events. 

The eventType field is device dependant and determines which event types to 
observe. For the standard device the eventType accepts multiple type values 
that are specified in W3C-DOM-Level2 [14]. For other devices the interpretation 
of eventType varies. 

For devices not mentioned here a new device name can be created. The node 
uses this string to identify the device driver plugged into the event dispatcher. By 
default all events of the specified device are reported. 

A detailed description of the DeviceSensor node and its fields can be found at 
“DeviceSensor” on page 69 in the Node Extensions section. 


Event 

The Event node is modeled after the W3C-DOM Events [14]. 


Event { 

eventln SFBool cancelBubble 

eventOut SFString type 

eventln SFBool returnValue 

eventOut SFVec2f screen 

eventOut SFVec2f client 

eventOut SFVec2f position 

eventOut SFVec3f xyz 

eventOut SFVec3f ypr 

eventOut SFBool altKey 

eventOut SFBool ctrlKey 

eventOut SFBool shiftKey 

eventOut SFInt32 keyCode 

eventOut SFString dataType 

eventOut SFString data 

eventOut SFInt32 button 


A detailed event description can be found at “Event” on page 71 in the Node 
Extensions section. 


205 





Related Documents - Generic Input Handling 


For drag and drop-events the dataType- and data fields have been added. 
The dataType field can have the following values: 



<dataType> ::= File | URL | HTML | Text | Image 


The data field delivers the URL of the data. 

For advanced input devices the built in Event node can be replaced by a device¬ 
specific Event node. The DeviceSensor must be initialized with the PROTO 
instance and the corresponding device. An external device driver is loaded 
which has the knowledge of its event proto and fills it with data, when polled by 
the DeviceSensor implementation. The device field identifies the device handler 
which can be built in as the keyboard and mouse handler or can be an external 
module for advanced input devices. If an external device handler can not be 
loaded by the browser the isActive field is always false. 

The following source code example illustrates the overriding of the event node 
by an own Prototype. 

PROTO SixDof 
[ 

eventOut 
eventOut 
eventOut 

] 

{} 

DEF ds Devic 

{ 

device " 

event DEF Data SixDof 

} 


SFVec3f 

SFVec3f 

SFInt32 


position 

rotation 

buttons 


as yaw pitch roll 

all buttons as bit mask 


eSensor 


SPACEMOUSE" 


Data can be routed either from the event field. Note this fires every time the 
driver has changed a field on the PROTO instance - 

ROUTE ds.event TO inputScript.onSpaceMouse 

or from the individual fields on the PROTO instance. 

ROUTE Data.position TO inputScript.onPosition 
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MouseSensor 

The MouseSensor is a more special form of the DeviceSensor. It reports the 
events of the mouse. This is part of what the DeviceSensor does in standard 
mode. Content authors may use this sensor if only mouse events are needed 

MouseSensor { 

eventln SFBool 

exposedField SFBool 
eventOut SFVec2f 

eventOut SFVec2f 

eventOut SFBool 

eventOut SFBool 

eventOut SFBool 

eventOut SFFLoat 

eventOut SFBool 

} 

A detailed descriptions of all fields can be found at “MouseSensor” on page 91 
in the Node Extensions section. 


eventsProcessed 

enabled TRUE 

client 

position 

lButton 

mButton 

rButton 

mouseWheel 

isActive 


KeySensor 

The KeySensor is a more special form of the DeviceSensor. It reports the events 
of the key board. This is part of what the DeviceSensor does in standard mode. 
Content authors may use this sensor if only keay board events are needed. 


A shortcoming of the VRML200x proposed KeyboardSensor is that the node 
catches all keyboard events. If certain keys are normally associated to the 
browser, they are either not processed in the scene or by the browser. Following 
the W3C-DOM-proposal [14] we propose to add a eventsProcessed field. 


KeySensor { 


eventln 

SFBool 

eventsProcessed 

exposedField 

SFBool 

enabled T] 

eventOut 

SFInt32 

keyPress 

eventOut 

SFInt32 

keyRelease 

eventOut 

SFInt32 

actionKeyPress 

eventOut 

SFInt32 

actionKeyRelease 

eventOut 

SFBool 

shiftKey changed 

eventOut 

SFBool 

controlKey changed 

eventOut 

SFBool 

altKey_changed 

eventOut 

SFBool 

isActive 


TRUE 


blaxxun 


A KeySensor node generates events when the user presses keys on the key¬ 
board. The KeySensor supports the notion of "keyboard focus". If there are mul- 


207 





Related Documents - Generic Input Handling 


tiple KeyboardSensors and/or stringSensors in a world, only one will gen¬ 
erate events at any given time. 

Note the KeySensor is not affected by its position in the transformation hierarchy. 

A detailed description of the fields of this node and the send event values can be 
found at the “KeySensor” on page 81 node description. 


Custom Curor 

For implementing a customized navigation the author should implement a proper 
cursor-mode to inform the user of navigation changes. The browser call 

browser.setCursor(SFString mode) 

mode: walk, slide, fly, beamto, examine, pan 

switches the appearance of the cursor. The world builder thus may change the 
appearance comparable to the browser automatically changing the appearance 
of the cursor over sensor nodes. Note that while the user is navigating, no sensor 
cursors are shown. 


Old Input Handling (<Contact4.4) 

The following paragraph is ONLY valid for earlier versions of blaxxun Contact. In 
order to implement Userlnput handling for blaxxun Contact5 or higher we recom¬ 
mend using the above mentioned nodes. 

Earlier versions of Contact didn’t support the mentioned sensors. In order to 
implement a custom input handling for older browsers it was necessary to regis¬ 
ter an observer to the Browser events. Setting an observer requires the addition 
of a route or an eventoutobserver to the browsers SFNode eventOut 
event_changed. This is a code fragment for adding the event observer: 

function initialize () { 

// tell what events 
m=Browser.eventMask; 
oldMask=m; 

m = m | (1<<4) | 1; // mouse up & down 

Browser.eventMask = m; 

// add event observer 

Browser.addRoute(Browser,'event_changed',inputHandler,'onEvent 
') ; 
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This are the supported mask values: 

mousedown = 1 
mousemove = 1<<1 
mouseout = 1<<2 
mouseover = 1<<3 
mouseup = 1<<4 
keydown = 1<<5 
keyup = 1<<6 
keypress = 1<<7 
click = 1<<8, 
dblclick = 1<<9 


This is a code fragment for the event callback handler: 

DEF inputHandler Script { 
eventIn SFNode onEvent 
url "j avascript: 
function onEvent(e,t) 

{ 

if (e.type == 'mousemove' && e.button == 0) 

{ 

return; // to many prints 

} 

print('Event type='+e.type+' at='+t); 

print(' button='+e.button+' shiftKey='+e.shiftKey+' 
ctrlKey='+e.ctrlKey+' altKey='+e.altKey); 

print(' position='+e.position+' keyCode='+e.keyCode+' 

ctrlKey='+e.ctrlKey+' altKey='+e.altKey); 

if (e.type == 'mouseup' && e.button == 2) 

{ // test to handle rbutton menu 
e.returnValue = 0 ; 

} 

} " 

} 

All input event properties are reported using only one Event node. The default 
Browser eventHandling for that event can be turned off by setting the return¬ 
Value to 0. The event types keypress, click, mouseover, and mouseout are not 
supported 
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Multitexturing 

Introduction 

Modern graphic APIs like Microsoft DirectX 7 and OpenGL 1.2 support hardware 
accelerated multi texturing and more sophisticated texture features. 

Contact 5.0 provides a new set of nodes enabling the VRML world builder to use 
these advanced texture features: 

• MultiTexture - allows to set multiple textures, textureTransforms and 
modes for an appearance 

• MultiTextureCoord - allows to specify multiple texture coordinate sets for 
geometry nodes 

• TextureCoordGen - allows to automatically generate texture coordinates. 

• CompositeTexture3D - allows to render a subscene dynamically to a tex¬ 
ture 

This section covers usage, implementation notes and examples. 



Fig. 8: Multitexturing used in Quake3 


Multi texturing 

Typical hardware today can handle at least 2 textures in a single step, top of the- 
line hardware already allows 4 textures. 
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In this example for abasic light map, Texture 2 is added on top of texture 1: 



VRML 97 already defines support for one texture, the new nodes allow to set all 
texture related attributes for n channels using MF fields 


Texture 

Texture 

Node 

Transform. 

appear- 


ance.texture 


ImageTex- 

appear- 

ture {...} 

ance.texture- 


Transform 


TextureTrans- 


form {} 

MultiTexture { 

MultiTexture { 

texture [ 

textureTrans- 

ImageTex- 

form [ 

ture {...} 

TextureTrans- 

ImageTex- 

form {...} 

ture {...} 

TextureTrans- 

] 

form {...} 




Texture 

Texture 

coordinate 

mode 

geome¬ 
try.texCoord 

TextureCoor- 

implicit in 

dinate {coord 

lightmodel 

[]} 

REPLACE / 
MODULATE 

MultiTexture- 

MultiTexture { 

Coord { 

mode [ 

coord [ 

"MODULATE" 

TextureCoor- 

"MODULATE" 

dinate { 
coord [ ] 

} 

TextureCoor- 
dinate { 
coord [ ] 

] 

} 


] 
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Nodes 


MultiTexture 

MultiTexture { 

exposedField SFBool materialColor FALSE 

# if TRUE modulate RGB textures with material color 

exposedField SFBool materialAlpha FALSE 

# if TRUE modulate RGBA GRAY-A textures with material alpha 

exposedField MFString mode [] 

# type and operation indication for texture 

exposedField MFNode texture [] 

# list of single Textures (ImageTexture PixelTexture 
MovieTexture) 

exposedField MFNode textureTransform [] 

# list of single TextureTransform nodes 

exposedField SFColor color 111 

# factor color argument for FACTOR blendmodes 

exposedField SFFloat alpha 1 

# factor alpha argument for FACTOR blendmodes 

} 

Main Functionality 

MultiTexture enables multi-texturing: a 3D object is textured with a texture com 
posed from several individual textures. Use it as a value for the texture field in 

an Appearance node. 


Detailed Semantics 

The texture field contains a list of Texture nodes, e.g. ImageTexture, Pixel- 
Texture, MovieTexture, CompositeTexture3D. 

The flags materialColor and materialAlpha allow to override specific 
VRML 97 lighting formulas. 

If materialColor is TRUE, RGB textures are modulated with the Material 
dif f usecolor or with the object vertexcolor (if present). Use it to modulate 
RGB RGBA textures with the color resulting from the Material or the primitive 
Vertex colors. 
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If materialAlpha is TRUE, alpha textures are modulated with the Material 
transparency alpha value. 


The field mode controls the type of blending operation. The VRML97 available 
modes correspond to MODULATE for a lit Appearance, and REPLACE for an 
unlit Appearance 


For a detailed description of the fields please read in the Node Extensions about 
“MultiTexture” on page 94 
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Possible modes 

MODULATE 

REPLACE 
MODULATE2X 


MODULATE4X 


ADD 


ADDSIGNED 


ADD SIGNED 2 X 


SUBTRACT 


ADDSMOOTH 


BLENDDIFFUSEALPHA 


BLENDTEXTUREALPHA 


BLENDFACTORALPHA 


multiply texture color with current 
color 

Argl * Arg2 

replace current color with Arg2 
Multiply the components of the argu¬ 
ments, and shift the products to the 
left 1 bit (effectively multiplying them 
by 2) for brightening 
Multiply the components of the argu¬ 
ments, and shift the products to the 
left 2 bits (effectively multiplying 
them by 4) for brightening. 

Add the components of the argu¬ 
ments 

Argl +Arg2 

Add the components of the argu¬ 
ments with a -0.5 bias, thus the 
effective range of values is from -0.5 
to 0.5. 

Add the components of the argu¬ 
ments with a -0.5 bias, and shift the 
products to the left 1 bit. 

Subtract the components of the sec¬ 
ond argument from those of the first 
argument. 

Argl -Arg2 

Add the first and second arguments, 
then subtract their product from the 
sum. 

Argl + Arg2 - Argl * Arg2 = Argl + 
(1 -Argl) * Arg2 

Linearly blend this texture stage, 
using the interpolated alpha from 
each vertex. 

Arg1*(Alpha) + Arg2*(1-Alpha) 
Linearly blend this texture stage, 
using the alpha from this stage's tex¬ 
ture. 

Arg1*(Alpha) + Arg2*(1 -Alpha) 
Linearly blend this texture stage, 
using the alpha factor from the Mul- 
tiTexture node. 

Arg1*(Alpha) + Arg2*(1 -Alpha) 
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BLENDCURRENTALPHA 

MODULATEALPHA_ADDCOLOR 

MODULATEINFALPHA_ADDCOLOR 

MODULATEINVAL PHA_ADDAL PHA 

OFF 

SELECTARG1 

SELECTARG2 


Linearly blend this texture stage, 
using the alpha taken from the previ¬ 
ous texture stage .Arg1*(Alpha) + 
Arg2*(1 -Alpha) 

Modulate the color of the second 
argument, using the alpha of the first 
argument; then add the result to 
argument one. 

Argl .RGB + Argl .A*Arg2.RGB 
Similar to 

MODULATEALPHA_ADDCOLOR, 
but use the inverse of the alpha of 
the first argument. 

(1 -Argl .A)*Arg2.RGB + Argl .RGB 
Similar to 

MODULATECOLOR_ADDALPHA, 
but use the inverse of the color of the 
first argument. 

(1 -Argl .RGB)*Arg2.RGB + Argl .A 
Turn off the texture unit 
use color argument 1 
Argl 

use color argument 1 
Arg2 


Compound modes 

A mode can be prefixed with one argument operator: 


default 


DIFFUSE 


SPECULAR 


FACTOR 


the second argument color (ARG2) 
is the color from the previous render¬ 
ing stage (DIFFUSE for first stage) 
The texture argument is the diffuse 
color interpolated from vertex com¬ 
ponents during Gouraud shading 
The texture argument is the specular 
color interpolated from vertex com¬ 
ponents during Gouraud shading. 
The texture argument is the factor 
(color, alpha) from the MultiTexture 
node 
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After the argument operator, the mode can be prefixed with the following modifier 
operators: 

complement^ Invert the argument so that, if the 

result of the argument were referred 
to by the variable x, the value would 
be 1.0 minus x 

alphareplicate_ Replicate the alpha information to all 

color channels before the operation 
completes 

Mode can contain an additional Blending mode for the alpha channel, eg. "mod¬ 
ulate , replace" specifies Color = (Argl .color * Arg2.color, Argl .alpha) 

The textureTransform field allows to individually transform each subtexture coor¬ 
dinate space. If textureTransform is NULL the transform is set to the inden- 
tity. 

The type field is reserved for future use. 

The number of used texture stages is determined by the length of the texture 
field. If there are fewer mode values, the default mode is "MODULATE", if there 
are fewer textureTransform values, the tranform for the channel is set to identity. 

MultiTextu reCoordinate 


MultiTextureCoordinate { 

exposedField MFNode texCoord [] 

# list of single TextureCoordinate nodes 

} 


Main Functionality 

MultiTexture requires multiple texture coordinates per vertex. This node can be 
used to set the texture coordinates for the different texture channels. 


Detailed Semantics 

Each entry in the texCoord field may contain a TextureCoordinate or Tex- 
tureCoordGen node. 

For a MultiTexture node with an IndexedFaceSet without a MultiTex¬ 
tureCoordinate texCoord node, texture coordinates for channel 0 are rep¬ 
licated along the other channels. Likewise if there are too few entries in the tex¬ 
Coord field, the last entry is replicated. 
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Please read also the Node Extensions section about “MultiTextureCoordinate” 
on page 96 

Example: 

Shape { 

appearance Appearance { 
texture MultiTexture { 

mode [ "MODULATE" "MODULATE" ] 
texture [ 

ImageTexture { 
url "brick.jpg" 

} 

ImageTexture { 
repeats FALSE 
repeatT FALSE 
url "light_gray.png" 

} 


textureTransform [ 

TextureTransform {} 

TextureTransform { scale 0.5 0.5 } 


} 

} 

geometry IndexedFaceSet { 

texCoord MultiTextureCoord { 
texCoord [ 

TextureCoordinate { ... } 
TextureCoordinate { ... } 


} 


} 


} 


TextureCoordGen 

TextureCoordGen { 

exposedField SFString mode "SPHERE" 
exposedField MFFloat parameter [] 

} 
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Main Functionality 

TextureCoodGen allow automatic generation of texture coodinates for geometry 
shapes. 


Detailed Semantics 

Use this node to set the texture coordinates for a node with a texCoord field. 

mode describes the algorithm used to compute texture coordinates: 

sphere Creates texture coodinates for a 

spheric environment or "chrome" 
mapping based on the vertex nor¬ 
mals transformed to camera space. 

u = Nx/2 +0.5 
v = Ny/2 +0.5 

u and v are the texture coordinates 
being computed, Nx and Ny are the 
x and y components of the camera- 
space vertex normal. If the normal 
has a positive x component, the nor¬ 
mal points to the right, and the u 
coordinate is adjusted to address 
the texture appropriately. Likewise 
for the v coordinate: positive y indi¬ 
cates that the normal points up. The 
opposite is of course true for nega¬ 
tive values in each component. If the 
normal points directly at the camera, 
the resulting coordinates should 
receive no distortion. The +0.5 bias 
to both coordinates places the point 
of zero-distortion at the center of the 
sphere map, and a vertex normal of 
(0, 0, z) addresses this point. 

Note that this formula doesn’t take 
account for the z component of the 
normal. 

cameraspacenormal Use the vertex normal, transformed 

to camera space, as input texture 
coordinates, resulting coordinates 
are in -1..1 range 
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CAMERASPACEPOSITION 

Use the vertex position, transformed 
to camera space, as input texture 
coordinates 

CAMERASPACEREFLECTIONVEC- 

TOR 

Use the reflection vector, trans¬ 
formed to camera space, as input 
texture coordinates. The reflection 
vector is computed from the input 
vertex position and normal vector. 

R=2 * DotProd(E,N) * N -E; 

In the preceding formula, R is the 
reflection vector being computed, E 
is the normalized position-to-eye 
vector, and N is the camera-space 
vertex normal. Resulting coordi¬ 
nates are in -1 ..1 range. 

SPHERE-LOCAL 

Sphere mapping but in local coordi¬ 
nates 

COORD 

use vertex coordinates 

COORD-EYE 

use vertex coordinates transformed 
to camera space 

NOISE 

computed by applying Perlin solid 
noise function on vertex coordi¬ 
nates, parameter contains scale & 
translation [scale.x scale.y scale.z 
translations translation^ transla¬ 
tions] 

NOISE-EYE 

same as above but first tranform ver¬ 
tex coordinates to camera space 

SPHERE-REFLECT 

similar to "CAMERASPACERE- 
FLECTIONVECTOR" with optional 
index of refraction (see NVIDIA 
paper), parameter[0] contains index 
of refraction Resulting coordinates 
are in -1..1 range. 

SPHERE-REFLECT-LOCAL 

similar to "SPHERE-REFLECT", 
parameter[0] contains index of 
refraction, parameter^ ..3] the eye 
point in local coordinates. By ani¬ 
mating parameter [1..3] the reflec¬ 
tion changes with respect to the 
point. Resulting coordinates are in - 
1..1 range. 


Some modes are hardware accelerated, e.g. they do not slow rendering signifi¬ 
cantly. 
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Compos iteT ext u re3 D 

CompositeTexture3D{ 
exposedField MFNode children NULL 
exposedField SFInt32 pixelWidth -1 
exposedField SFInt32 pixelHeight -1 
exposedField SFNode background NULL 
exposedField SFNode fog NULL 
exposedField SFNode navigationlnfo NULL 
exposedField SFNode viewpoint NULL 
} 

Main Functionality 

The CompositeTexture3D node represents a texture mapped onto a 3d object 
composed from a 3d scene. 


Detailed Semantics 

Behaviors and user interaction are enabled with CompositeTexture3D. Howev¬ 
er, no user navigation is possible on the textured scene and sensors contained 
in the scene which forms the CompositeTexture3D shall be ignored. 

The children field is the list of 3D root and children nodes that define the 3d 
scene that forms the texture map. 

The pixelwidth and pixelHeight fields specify the ideal size in pixels of 
this map. If no value is specified, an undefined size will be used. This is a hint for 
the content creator to define the quality of the texture mapping. 

The background, fog, navigationlnfo and viewpoint fields represent 
the current values of the bindable leaf nodes used in the 3d scene. The semantic 
is the same as in the case of the Layer3D node. This node can only be used as 
a texture field of an Appearence node. 
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Fig. 9: The 3D view of the earth is projected onto the 3D cube 
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please see also the node reference “CompositeTexture3D” on page 65 in the 
Node Extensions section and read the “Contact 5.0 implementation notes” on 
page 221! 


Contact 5.0 implementation notes 

DirectX 7 Renderer 

Recent graphics cards implement 2 texture stages e.g. Matrox G400, ATI Rage, 
Nvidia TNT 2, GeForce. 2 Textures are also available in the Direct X 7 software 
renderer (high quality). Most notebook 3d graphic chips only support one. 

The supported blending modes are highly dependent on the chip and driver revi- 
son. MODULATE, ADD, REPLACE are usually available. The supported modes 
can be queried using the Microsoft DX Caps Viewer tool available in the Direct 
X SDK. With Contact 5.0 you may query the supported modes in VRMLscript 
using Browser.getOption('textureBlendModes'). 

More information about blending modes is available in the Microsoft Direct X 
SDK. 

Compos it eTexture3D is supported by software and most hardware drivers. 
Compos it eTexture3D depends on size and number of node instances and 
can use a lot of video memory resources. You should take care to ensure 
enough video memory is available. 

The texture coordinate modes cameraspacenormal, cameras pace posi¬ 
tion, cameraspacereflectionvector are directly mapped to the Direct 
3D API, resulting in very litlle overhead. All other modes are computed in soft¬ 
ware at each rendering cycle. 

OpenGL Render 

OpenGL 1.1 does support multitexturing only if the ARB_multitexture extension 
is present. 

Advanced blending modes are supported if the EXT_texture_env_combine 
extension is present, the ADD mode with the EXT_texture_env_add exten¬ 
sion. 

specular_ modifier is not supported. 

Blending modes subtract addsmooth modulatealpha_addcolor 

MODULATEINVALPHA_ADDCOLOR MODULATEINVCOLOR_ADDALPHA 
selectarg 2 DOTPRODUCT3 are never supported. 
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Blending modes blenddiffusealpha lendtexturealpha blendfac- 
toralpha blendcurrentalpha are implemted in Contact 5.0. 
EXT_texture_env_combine extension needs to be present. 

CompositeTexture3D is not supported in the OpenGL version. 

The texture coordinate modes cameraspacenormal and cameraspacere- 
flectionvector are supported if the extension NV_texgen_reflection is 
present. 

Contact 5.0 Automatic replication of too few TextureCoord entries in Multi- 
TextureCoordinate is unsupported (will be fixed in 5.1) 

Hardware dependency 

You can safeley assume that 1 texture, and modes modulate replace , are 
supported. 

Most 3D boards support at least 2 textures, modes modulate replace add, 
type color. 

The number of texture units can be queried using a Browser.getCap() vrmlscript 
extension call. Contact3D ignores all textures exceeding the graphics cards tex¬ 
ture channels. 


Usage cases 

MultiTexturing 

Lightmapping 

The effect of a light is added using one of the ADD modes, you can animate the 
light by changing texture transform, texture coordinates or the light texture. 


Darkmapping 

The light texture is multiplied with the base texture. 


Basetexture & environment mapping 

The mode "sphere" is very useful for generating spherical environment map¬ 
ping based on the vertex normals of an object tranformed to camera space. The 
object must be curved, with shared vertices in order to see an effect. For flat 
shapes cameraspacereflectionvector results in better results, as the 
computed reflection vector takes the eye position into account. 
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The texture coordinate modes came rasp acenormal and cameras pacere- 
flectionvector result in texture coordinates in the -1 .. 1 range. If the texture 
is not tileable a TextureTransform can be used to normalize the coordinates to 
the 0 ..1 range. 


Fading between two textures 

The blendmode for the second texture can be set to BLENDFACTORALPHA.The 
alpha field of the MultiTexture node specifies the fading factor between tex¬ 
ture 1 & 2. 


Replacing Alpha using a texture 

mode[1]= ll ALPHAREPLICATE_MODULATE M 


Examples 

TextureCoordGen 
mode "SPHERE" 

• Chrome mapped Venus: wrlvenus_chrome.wri 

• Environmapped Venus: venus_env.wri 

• Environmapped Venus using a color gradient texture: 

venus_gradient.wri 

• Environmapped Teapot: teapot4_env.wri 

• Environmapped Teapot using hardware mode: teapot4_env_hw.wri 

• Texture used for environmapping: spheremap.jpg 

• Animated Nurbs Surface environmapped: nurbschromic_bombs.wri 


mode "NOISE" 

• texgen_noise.wri 
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mode cycle 

Single texture with different texture coordinate generation modes, click on shape 
to cycle through modes: texgen_mona.wri 


Multi Texture 

• Basic shape with 2nd added texture: ifs_lightmap.wri 

• Generated tunnel with light map, the lightmap is translated and scaled us 
ing TextureTransform : tunnelmtex.wri 

• 2 textures, click on shape to cycle through blending modes: ifs_mona.wri 

• Elevation grid with 2 textures : mount.wri 


Alpha mapping 

• Basic shape with diffuse texture, alpha channel is from 2nd texture: 

ifs_alphamap.wri 


Fading 

• Texture blend mode blendfactoralpha is used to fade between two 
different images: ifs_fade.wri 

• Basic shape with 2nd blendfactoralpha blended MovieTexture: 

ifs alien.wri 


Specular mapping 

Adding the effect of a second texture with a possibly view dependent texgen 
mode on top a base texture can be used for specular mapping: 

• Basic shape with 2nd sphere mapped texture: ifs_envmap.wri 

The current proposal and hardware API does not allow to apply a texture to the 
specular lighting component only and later combine this with a diffuse texture. 

• With the specular_ prefix you can use the specular color as input for 
texturing: ifs_specmap.wri 
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Detail Mapping 

Instead of using a high resolution texture texture detail is created by using a low 
resolution base texture and combining it with a tiled pattern which adds high fre¬ 
quency detail. In this example blendfactoralpha is used for the second "DE¬ 
TAIL" texture: ifs detail.wri 


Selective Blending 

The mode "blendtexturealpha" is used to blend in an image selectively de¬ 
pending on the textures alpha channel. In this example blendtextureal¬ 
pha, selectarg 2 is used for the second texture. selectarg 2 is used for the 
alpha argument because the shapes final alpha should come from the Material 
transparency or the transparency of the first texture: tunnel_detailtex.wri 


Bump mapping 

Is not yet supported, the field MFSTring type has been reserved to indicate bump 
mapping in future versions. 


Combined Examples (some features work in Direct X 7 only) 

• A logo with reflection mapping : x79logo.wri 

The letters are planar faces, texGen mode cameraspacereflection- 
vector is used to create texture coordinates for the second texture. The 
second texture is a color pattern ADDed on top of the base texture. Tex¬ 
ture transform of the second channel is animated to add effects. 

• Generated rooms with animated alpha factor and blending mode blend¬ 
factoralpha, Drag & Drop support: hrooms_portal_lightmap.wri 

• Landscape with 2nd texture and 2 particle systems, Texture dynamically 
rendered via CompositeTexture3D : ct_ground_fire.wri 

• Texture text with 2nd Texture effect: texturefont_mt.wri 


Authoring 

(R) 

3D Artists using discreet 3ds max4 may use the blaxxun Exporter for 3ds 
max4. With this it is possible to create multitextured scenes in 3ds max and 
export them to VRML using the MultiTexture extension nodes. Please read the 
documentation of the exporter for details. 
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The Quake3 BSP Converter, by John W. Ratcliff can export lightmapped scenes 
to VRML from the Quake3 BSP format. The original version can be found here 


225 





Related Documents - Render Culling and BSP-Tree Optimization 


http://www.flipcode.com/cgi-bin/msg.cgi?showThread=COTD- 

Q3BSP&forum=cotd&id=-1 


References 

OpenGL 

http://www.opengl.org/developers/documentation/overviews.html 

OpenGL extensions 

http://oss.sgi.com/projects/ogl-sample/registry/ 

http://oss.sgi.com/projects/ogl-sample/registry/ARB/multitexture.txt 

http://oss.sgi.com/projects/ogl-sample/registry/ARB/texture_env_add.txt 

http://oss.sgi.com/projects/ogl-sample/registry/ARB/texture_cube_map.txt 

http://oss.sgi.com/projects/ogl-sample/registry/EXT/texture_env.txt 

Nvidia White Papers 

http://www.nvidia.com/Marketing/Developer/DevRel.nsf/Whitepapers- 

Frame?OpenPage 

Lightmaps 

http://www.flipcode.com/tutorials/tut_lightmaps.shtml 
http://home.bip.net/tobias.johansson1/tut_lightmap.htm 
id software Quake III 
http://www.quake3arena.com/ 

Buildertools etc.http://www.planetquake.com/quake3/files.shtml 


Render Culling and BSP-Tree Optimization 

Overview 


226 


The Problem 

The handling of large worlds is currently not well supported by VRML 2.0 brows 
ers. Browsers could implement view culling using bounding box information 
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stored in Group nodes, but typical scenes are not well spatial organized for this 
optimization. Even then a large amount of invisible geometry needs to be 
checked and passed to the rendering subsystem. 


One Solution 

A common solution used in games is to subdivide the world into smaller parts, 
where the browser can quickly decide to draw or not to draw a part. One method 
is the Binary Space Partitioning Tree (BSP-Tree). The world is divided by an in¬ 
finite plane into the parts in front and behind the plane. The remaining parts are 
themselves recursively split until each part is a single object. 

In a True BSP-Tree, which can be rendered without the help of a z-buffer, each 
object is a single polygon. A polygon might get split if it crosses the plane of its 
parent tree node, a node stores also the list of polygon exactly on the plane. 

In a hybrid approach objects need not to be decomposed so far or can be com¬ 
bined with dynamic, moving parts that are not part of the BSP-Tree hierarchy. 
Here z-buffering is enabled, to ensure correct visibility. 


BSPTree Node 

blaxxun Contact supports an extension node which makes it possible to take ad¬ 
vantage of these optimization techniques. It is described in detail in the Exten¬ 
sion Nodes section at “BSPTree” on page 54 


Hints and techniques 

The optimization only works out, if the viewer is inside the limits of the world, and 
if the visibilityLimit in the worlds Navigationlnfo is specified as small as possible. 
The setting of visibilityLimit directly controls the amount of geometry passed to 
the rendering subsystem, and therefore the overall speed. Different Navigation- 
Info Nodes could be bound in different parts of the world where a different visi¬ 
bility is required. In Contact 3D the limit can also be controlled by using the jav¬ 
ascript extensions Browser.setVisibilityLimit(limit), Browser.getVisibilityLimit(). 

BspTree and the other culling nodes also provide performance improvements for 
collision detection, ground detection and general selections (Anchors, Touch- 
Sensor's). 

Inline nodes in culled branches of the scene graph are delayed loaded, until they 
become visible or no more other load operations are pending. 

Contact 3D renders BspTree per default with z-buffering enabled and front to 
back ordering. Front-to back ordering would lower z-overdraw, that means writ- 
ting the same pixel several times. To enable "True" BSP-Rendering, that means 
render from back to front without z-buffer, toggle the "x" key in blaxxun Contact 
3D. This will disable the standard z-buffer algorithm, and could further increase 
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the frame rate. For optimal results the tree should be a True-BspTree, that 
means all Geometry is properly sorted into the tree, terminal nodes are planar 
objects or convex, solid objects, all object intersection has been resolved. 

The blaxxun Contact 3D default is the hybrid mode, where z-buffering is used to 
compute visible pixels and the BSP-Tree helps culling. In hybrid mode, it is not 
necessary to decompose objects up to the last polygon. 

The VRML VisibilitySensor is optimized in blaxxun Contact 3D in conjunction 
with BspTree’s and should be used for enabling/disabling complex animations. 
I.e. whenever the sub-graph becomes visible, an animation can be started by 
enabling the TimeSensors/Scripts, whenever the sub-graph becomes invisible, 
the TimeSensors are disabled. 

Other techniques that can be combined are: 

• use of LevelOfDetail (LOD nodes) to remove detail of objects far away 
from the viewer, 

• ProximitySensors to enable/disable scene graphs depending on viewer 
position 

Using the ScriptNode or the EAI an application could implement dynamic tree 
modification, by storing moving objects into their proper tree locations, or by 
loading/unloading scene sub-graphs depending on viewer location and move¬ 
ment. 

Unloading of scene graphs could be achieved by deleting nodes (e.g. Inline 
nodes) from the scene using a Script, or by assigning to the url of an Inline, 
blaxxun Contact 3D only loads Inline into memory, if the Inline load is part of the 
current traversed scene graph. In the BspTree scenario, an Inline would only be 
loaded if that subtree of the scene becomes visible. However the parsing (not the 
downloading) of an Inline into VRML Nodes currently causes a delay during an 
walk-through. 

When using BspTree or other culling nodes togeter with Inlines there is a mem¬ 
ory mangament optimization available in Contact 3D. 

The idea is to unload Inlines nodes, once they haven't been visible for some time. 
For example a large world is subdivided into several tiles, once the user travel to 
a certain area, tiles no longer visibile could be purged from memory. 

The unload algorithm is currently based only on the number of inlines currently 
loaded. During rendering each Inline get's the current timeStamp. Inline's not 
rendered any more due to culling having timeStamps in the past. 
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The optimization can controlled with the following javascript Browser object 
extension: 
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Browser.setUnloadMode(int minNotActivelnlines, float 
percentage factor to purge) 

The meaning of this function is: if the number of inlines currently not rendered is 
greater minNotActivelnlines, unload up to (number * percentage ) inline’s from 
memory if percentage < 0, abs(perscentage) is an absolute number of inlines to 
purge 

example : 

Browser.setUnloadMode(100,0.05) 

if (more than 100 loaded inlines are currently not rendered), delete 5 % of the 
inlines not used for the longest time (Improved heuristics could include the addi¬ 
tion of the memory resource consumed by an Inline’d SceneGraph). 

In such a scenario Browser viewpoint animation could become very costly, if the 
path crosses many regions currenlty not in memory. The extension 

Browser.setViewpointAnimation(FALSE) 

can be used to turn off Browser generated viewpoint transistions. 

The Bsp tree traversal order itself can be set with 

Browser.setBspMode(order) - set bsp Traversal order 

Browser.setBspLoadingMode( order) - set bsp inline Traversal 
order 


TRAVERSE_NORMAL 0 


TRAVERSE_BACK_TO_FRONT 1 


TRAVERSE_FRONT_TO_BACK 2 


Building BSP Trees 


For some type of scene there is a natural subdivision scheme, like quad-tree, 
oct-tree for Landscapes, connected rooms, buildings etc. A quad-tree approach 
can be found in the TileGrid EAI sample. Other examples could be the streets, 
tunnels or similar shapes, which could be subdivided along their spine curve. 


The GLView standalone browser has a BSP-Tree builder and Scene-graph opti¬ 
mizer. The following paragraph describes the use of this tool for building BSP- 
Trees. 
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First a suitable scene-graph for optimization or BspTree construction has to be 
found. 

The scene tree optimizer expands all Transforms, Groups, Inlines. Geometry 
nodes are converted to IndexedFaceSet nodes. The resultant Transform Matrix 
and any TextureTransform are applied to the Geometry. DEF / USES are 
expanded. 

A lookup process shares Material, ImageTexture and Appearance Nodes. 

For BSP-Tree purposes Anchors are applied to all resulting geometry individu¬ 
ally and there is the option of decomposing IndexedFaceSets into single polygon 
IndexedFaceSets ("Planar Shape"). 

In the standard, expected case the result is a long list of Shape nodes containing 
IndexedFaceSet’s. 

The Optimizer may currently not work correctly on graphs with ROUTES into 
Transforms or containing unsupported nodes like Billboard, LOD. Such cases 
may need some manual cleanup before or after the optimizer runs. 

As a second step the BspTree builder takes this list and builds a BspTree node 
hierarchy out of it. 

There are several approaches how to build the tree, GLView Contact 3D offers 
currently the following choices: 

Subdivision strategy 

• separation plane: 

for each IndexedFaceSet a convex hull is beeing computed and among 
the planes of two hulls, a plane which separates the two bodys is beeing 
selected, planar Shapes are direct candidates for separation planes. 

• use first planar object: 

search for the first planar Shape, other wise use "split along largest di¬ 
mension" 

• use largest planar object: 

earch for the largest planar Shape 

• split along largest dimension: 

take the bounding box of the current set of nodes and split the set along 
the axis with the largest size 

For the hybrid approach the option maxBspLevel allow to stop this tree building 
process after a certain subdivision level has been achieved. Depending on the 
number of final nodes, this process can take some time. So please be patient, 
especially if you subdivide objects into single faces. 
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Step by Step Instruction for Optimizer and BSP-Tree Builder 

• Start GLView 

• Load the VRML 2.0 scene 

• Open the Tree-Editor (Tools->Tree Editor) 

• Set the optimizer settings (Settings->Optimizer) 

Explanation of options : 

- keep inlines - if checked inline nodes will not be expanded 

- keep lods - if checked LOD nodes will not be expanded 

- ignore routes - if not checked nodes with ROUTES will not be expanded 

- expand objects into faces - all Shape nodes will be expanded into a set 
of one face IndexedFaceSets (much more computation, but necessary 
for True -Bsp Tree) 

- Build Bsp Tree - build BSP-Tree after optimization 

- Max Bsp Level - max Tree level for BSP 

- BspSearch limit - up to this limit different separation planes are evalu¬ 
ated to find a "best" splitting plane 

• For BSP- Tree Building set the options to the following 

- check "Build Bsp Tree" 

to expand the scene as much as possible: 

- uncheck "keep inlines" "keep lods" 

- check "ignore routes" 

• Close the dialog 

• In the Tree-Editor window double-click on the Nodes and children fields 
until you find the top-level node to be optimized 

• Start optimization using "Node->Operations->Optimize Tree" command 
in the menu or the right mouse popup menu. 

• save the new scene using "File->Save" menu command in the main win¬ 
dow 


Using the optimizer without BspTree building may also speed up the rendering 
of the scene, because the group hierarchy is being flattened, Materials/Textures 
are shared, transforms are applied. 
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Simplified BspTree interface 

Starting with blaxxun Contact 3D 3.51 there is a simple BspTree interface. The 
BspGroup specifies as children a list of nodes, where automatically a BspTree is 
constructed. A Group with a big list of static children could simply be replaced by 
a BspGroup node. 


EXTERNPROTO BspGroup[ 

field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 
eventOut SFNode bspTree] 

["urn:inet:blaxxun.com:node:BspGroup","http://www.blaxxun.com/ 
vrml/protos/nodes.wrl#BspGroup"] 

A detailed field description can be found in the Node Extensions section: “BSP- 
Group” on page 56 


Other culling mechanisms 

The current blaxxun Contact 3D BspTree implementation helps not in all cases, 
so far we could walk in a large outside landscape. Then we want to enter build¬ 
ings which may have very complex geometry inside. It is assumed for now that 
the complex things inside the rooms can't be viewed from outside, (the windows 
and Door's are opaque.) 

blaxxun Contact 3D introduces two more nodes to aid Occlusion culling. 

Occlusion 


EXTERNPROTO Occlusion[ 

field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField SFBool enabled 
exposedField SFNode proxy 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 
eventOut SFBool isActive 
eventOut SFTime enterTime 
eventOut SFTime exitTime 


["urn:inet:blaxxun.com:node:Occlusion" ] 
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Occlusion is a group node with an additional proxy geometry triggering an inside/ 
outside processing. Children would contain the inside view of the room, proxy 
would contain the bounding shape for the room, i.e. a Box {} node. 

During traversal the current viewpoint is compared with all geometry nodes in the 
proxy subgraph. If the viewpoint is outside all geometry nodes, children will be 
not visited for display. If the viewpoint is inside the proxy the children will be vis¬ 
ible. 

Whenever children become visible or invisible isActive, enterTime and exitTime 
events are generated similar to the ProximitySensor. 

Occlusion’s behaviour can be switched to the normal Group behaviour by setting 
enabled to FALSE. This is designed for cases where temporarily the room 
becomes visible from the outside, for example if a door or window has been 
opened, to look inside the room. 

Inclusion 

EXTERNPROTO Inclusion[ 

field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField SFBool enabled 
exposedField SFNode proxy 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 
eventOut SFBool isActive 
eventOut SFTime enterTime 
eventOut SFTime exitTime 

] 

[ "urn:inet:blaxxun.com:node:Inclusion"] 


Inclusion is somehow the inverse to Occlusion. Children are only traversed if the 
viewpoint is in one of the proxy objects or if proxy is NULL. In combination with 
BspTree’s if an Inclusion node becomes active, the node signals the BSP-Tree 
logic to stop processing. The idea is, once you are inside a room, you cannot see 
anything else. 

Simple cases where the proxy is a Box can be realized in standard VRML97 
using a ProximitySensor and a Script as demonstrated on the VRML sample’s 
page. 

The current implementation allows the following nodes inside the proxy scene 
graph: Group Transform, Box, Sphere, Cylinder, IndexedFaceSet (must be con¬ 
vex) 
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You may also read the Node Extensions chapter about “Inclusion” on page 78 
and “Occlusion” on page 97 

View Frustrum Culling 

The users viewpoint together with the view direction, the field of view and the vis¬ 
ibility limit defines a pyramid. Objects falling outside this pyramid are not visible. 
The lowlevel rendering engine Direct 3D used in Contact 3D automatically pro¬ 
vides this type of culling at the geometry level (Execute Buffers). Beginning with 
Contact 3D 3.051 view frustrum culling can be forced by specifiying a bboxSize 
field for Nodes like Group, Transform, Inline. GLView can be used to compute 
and update bounding boxes at certain scene graph levels. The bounding boxes 
are internally not automatically computed because too many culling checks 
could degrade performance, and bounding boxes cpmputed once could become 
invalid due to changes in the VRML scene caused by animations, scripts or the 
loading of Inlines. 

To indicate a scene graph Group which should be tested for view frustrum culling 
the following node can be used : 

EXTERNPROTO CullGroup[ 

field SFVec3f bboxSize 
field SFVec3f bboxCenter 
exposedField MFNode children 
eventln MFNode addChildren 
eventln MFNode removeChildren 

] 

["urn:inet:blaxxun.com:node:CullGroup", 

"http://www.blaxxun.com/vrml/protos/nodes.wrl#CullGroup"] 

CullGroup automatically computes a bounding box for children, the first time the 
node is beeing rendered. CullGroup can be used like a normal group, but chil¬ 
dren should not move outside the limits of the initially computed bounding box. 
If there are animations in the children scene graph, they should be enclosed in 
Group nodes with an explicit bboxSize large enough to cover the whole possible 
extent. 


Cells&Portals 

Introduction 

VRML 97 currently lacks tools for enabling visibility managment for indoor envi¬ 
ronments. An ideal browser implementation could analyze the scene graph and 
apply occlusion culling algorithms during rendering, but this seems currently not 
feasible given the dynamic nature of a VRML scene graph. 
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A well known occlusision culling technique are Cell & Portals. The idea in short: 
given a set of rooms connected by windows and doors, for a given room if a win¬ 
dow is not visible, the room viewed through the window is not visible either. 


Principle 


As a compact description the reader is refered to the paper: Faster 3D Game 
Graphics by Not Drawing What Is Not Seen Kenneth E. Hoff III. ACM Cross¬ 
roads, 1997. 

The following illustrations describe the principle 



Here the world is divided into sets of polygons grouped by rooms or cells (differ¬ 
ent colors) that are separated by doorways or portals (dashed lines). Only cells 
visible through sequences of portals are drawn. Here there is no advantage 
since all cells can be seen through the portals. However, if this was used with 
view frustrum and backface culling, we could still reduce the load. 


When the viewpoint moves into a cell where long sequences of portals are no 
longer visible, large portions of the world are culled at a significant fraction of the 
cost of other techniques. Only two portal overlap tests were required. 
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Node definitions 

A Cell Portal graph is routed by a CellGroup node. The list of cells is listed in the 
cells field of the CellGroup. The Portal helper node defines the "window" geom¬ 
etry and points to the Cell seen. 

A detailed description of the below mentioned nodes and their fields can be 
found at “Cell” on page 60, “CellGroup” on page 62 and “Portal” on page 103 in 
the Node Extensions section. 

Cell 

Cell is a grouping node similarily to Group. 

Cell { 

exposedField SFVec3f bboxSize -1 -1 -1 
exposedField SFVec3f bboxCenter 000 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventIn MFNode removeChildren 
exposedField MFNode portals 
exposedField SFInt32 content 0 

} 


Portal 

Portal specifies the portal's geometry. A portal is the ’doorway’ by which different 
cells are connected. 

Portal { 

exposedField SFBool enabled TRUE 
exposedField SFBool ccw TRUE 
exposedField SFNode coord NULL 




















exposedField SFNode cell NULL 

} 
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Cellgroup 

Cellgroup is a grouping node similarily to Group. 

CellGroup[ { 

exposedField SFVec3f bboxSize -1 -1 -1 
exposedField SFVec3f bboxCenter 000 
exposedField SFInt32 range -50 
exposedField MFNode cells [] 
exposedField MFNode children [] 
eventln MFNode addChildren 
eventln MFNode removeChildren 
eventOut MFNode activeCells 

} 


BspTree 

The BspTree node is used as a helper node in this context structuring the scene 
graph. 


BspTree { 

exposedField SFRotation plane 0010 
exposedField SFNode front NULL 
exposedField SFNode overlap NULL 
exposedField SFNode back NULL 

} 

Example structure 

This is the scene graph for set of 2*2 rooms connected with doors: 

CellGroup { 
cells [ 

DEF C0_0 Cell { 
children [ 

] 

portals [ 

DEF PC1_0 Portal { 
coord Coordinate { 

point [70 14.5 28,70 14.5 42,70 0 42,70 0 28] 

} 

cell DEF C1_0 Cell { 
children [ 
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portals [ 

DEF PC1_1 Portal { 
coord Coordinate { 
point [ 

112 14.5 70, 98 14.5 70, 98 0 70, 112 0 70 

] 

} 

cell DEF Cl_l Cell { 
children [ 

] 

portals [ 

DEF PC1_0_1 Portal { 
coord Coordinate { 
point [ 

98 14.5 70, 

112 14.5 70, 

112 0 70, 

98 0 70 


} 

cell USE C1_0 

K 

DEF PC0_1 Portal { 
coord Coordinate 
point [ 

70 14.5 112, 

70 14.5 98, 

70 0 98, 

70 0 112 


{ 


cell DEF C0_1 Cell { 
children [ 

] 

portals [ 

DEF PC0_0 Portal { 
coord Coordinate { 
point [ 

28 14.5 70, 

42 14.5 70, 

42 0 70, 

28 0 70] 

} 

cell USE C0_0 

K 

DEF PC1_1_1 Portal { 
coord Coordinate { 
point [ 

70 14.5 98. 
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} 


70 14.5 112, 
70 0 112, 

70 0 98] 

cell USE Cl_l 

K 


} 


} 


} 

K 

DEF PC0_0_1 Portal { 
coord Coordinate { 
point [ 

70 14.5 42, 

70 14.5 28, 

70 0 28, 

70 0 42 


} 

cell USE C0_0 

} 


} 

K 

DEF PC0_1_1 Portal { 
coord Coordinate { 



point [ 


42 

14.5 70, 


28 

14.5 70, 


28 

0 70, 


42 

} 

0 70] 

} 

1 

cell 

USE C0_1 

J 

}. 

USE 

o 

o 

1 

i- 1 


USE 

n 

M 

1 

O 


USE 

Cl 1 



] 

children BspTree { 
plane 100 -70 
front BspTree { 
plane 001 -70 
front USE C0_0 
back USE CO 1 


} 
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back BspTree { 
plane 001 -70 
front USE C1_0 
back USE Cl_l 

} 

} 

} 
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VRMLScript Reference 

blaxxun Contact supports VrmIScript, a subset of Javascript, in the Script node. 
A reference on VRMLScript can be found here. Extensions to the functionality 
mentioned in this reference are available and are described in detail in the chap¬ 
ter “Scripting” on page 29. 

Please note, that blaxxun3D, the pure Java core imlementation of the X3D pro¬ 
posal, does not support the Script node. In order to add scripting functionality to 
blaxxun3D, please use the methods of the Java- or Javascript-EAI mentioned in 
“blaxxun3D” on page 165 in the API chapter. Also the “blaxxun X3D-Proposal” 
on page 195 may be of interest in this case. 


End of document 





